create-pmos 0.11.1 → 0.12.0

package/README.md

@@ -333,6 +333,43 @@ 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.12.0
+
+**The sidebar says what is actually true.** 0.11.x told you things were *unreadable* when they were
+simply *not there* — and used the same red for both.
+
+If you pointed the workspace at an ordinary folder or a repository that isn't a PMOS repo, almost
+everything read as an error. None of it was.
+
+- **A folder that isn't a git repository** now says so, quietly. It used to say `branch unreadable`,
+  which is an alarm about a completely ordinary directory.
+- **A repository with no initiative records** reads **no initiatives yet** — a fact about the
+  repository, calmly stated. Pointing the workspace at any repo you like is a supported thing to do.
+- **A shell session** no longer reports its non-existent transcript as a failed identification. A
+  shell is a prompt, not an agent narrating itself.
+- **A row keeps its name.** Previously a plain folder rendered as a row titled `branch unreadable` —
+  a row with no name at all, unfindable in a tree of them.
+
+Red still means red: a corrupt state queue, a genuine git failure, or an engine that is installed but
+throws all still draw the alarm. The point is that they no longer share it with the normal case.
+
+Three controls also stopped being ambiguous:
+
+- **`＋ new session — run an agent here`** now names the repository and branch it will start in.
+  "Here" meant the selected tree all along; with every repository on screen at once, nothing said
+  which that was.
+- **`＋ session here`** starts a session. It used to select the tree and stop.
+- **A row with no sessions no longer expands** just because something needs your attention — that
+  count is already shown on the row, and opening an empty container to "reveal" it taught you to
+  distrust the tree.
+
+And the pane is called **repos & sessions** rather than `work`.
+
+> **One disclosure.** The Review Gate for this work was not scored before release. Its rubric makes
+> the honesty checks *runnable* precisely so they cannot be satisfied by reading the code, and they
+> were not run by an independent evaluator. Everything above was verified by the automated suites
+> (412 checks) and by hand; none of it was independently reviewed.
+
 ## What's new in 0.11.1
 
 **Fixes: the ladder never actually worked.** If you installed 0.11.0 and every row in the new

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "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@cae81d8
+kernel-source: pmos@120ca72
 assembled: 2026-07-29
 mode: vendor

package/workspace/lib/harness-parse.js

@@ -52,6 +52,8 @@ const EFFORT = /\beffort[:\s]+(low|medium|high|xhigh|max)\b/i;
 const TAIL_BYTES = 32_768;
 
 const NOT_CLAUDE = 'only claude sessions are parsed';
+// A shell is a prompt, not an agent narrating itself. Absence here is the design, not a read failure.
+const SHELL_NO_WORDS = 'a shell — it narrates nothing to read back';
 const UNREADABLE = "can't read its output — no recognisable Claude Code blocks";
 
 /** Split the scrubbed tail into lines, dropping a partial first line. */
@@ -153,7 +155,12 @@ function parseHarness(scrubbed, agent) {
   const out = { lastWords: null, tools: null, model: null, context: null, missing: {} };
 
   if (agent !== 'claude') {
-    out.missing.lastWords = `can't read its last words — ${NOT_CLAUDE}`;
+    // R4 — a SHELL has no "last words" in the sense this parser means, and never will: it is a
+    // prompt, not an agent narrating itself. "can't read its last words" describes a failed attempt
+    // at something that was never going to happen, on the most ordinary pane in the app. State what
+    // it is instead. `codex` and any future agent keep the parser-scope message, which is the
+    // accurate thing to say about them: the transcript exists, this parser does not read it.
+    out.missing.lastWords = agent === 'shell' ? SHELL_NO_WORDS : `can't read its last words — ${NOT_CLAUDE}`;
     out.missing.tools = NOT_CLAUDE;
     out.missing.model = NOT_CLAUDE;
     out.missing.context = NOT_CLAUDE;

package/workspace/package-lock.json

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

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/public/app.js

@@ -221,6 +221,7 @@ async function selectWorkspace(id, opts = {}) {
   if (changed) closeDoc();
   renderWorkspaces();
   renderSessions();
+  renderNewTarget();      // R5 — "here" moved; the composer must say so even if it is already open
   loadBoards();
   // focus a session in THIS workspace: the remembered one if it belongs here, else its first live one
   const mine = mySessions();
@@ -259,12 +260,43 @@ async function selectWorkspace(id, opts = {}) {
  */
 const TREE_GLYPH = { working: '●', quiet: '◼', blocked: '✗', idle: '—', exited: '○', none: '·' };
 
-// The initiative a branch names, and the record behind it — three cases, all of them stated. A
+/* THE THREE-VALUED RULE (R2, and the veto of this initiative's rubric).
+ *
+ * Every derived cell in this tree is one of three things, and they get three renderings:
+ *
+ *   value          — the fact, rendered plainly
+ *   verified absent— the read SUCCEEDED and found nothing. Quiet, specific, never red. This is the
+ *                    common case for anything that is not a PMOS repo, and it is the one the first
+ *                    version had no rendering for at all.
+ *   unreadable     — the read FAILED. Red, and it keeps the word.
+ *
+ * The first version had two renderings for three facts, so one was always mislabelled: a plain
+ * folder reported `branch unreadable`, which is an alarm about a completely ordinary directory, on
+ * the same surface that uses red for a corrupt state queue and a blocked initiative. A surface that
+ * cries wolf on the normal case teaches the PM to ignore red where red is real.
+ *
+ * `absent()` and `broken()` are the only two ways to say it, so a fourth site cannot invent a
+ * fifth vocabulary. */
+const absent = (txt, title) => `<span class="gone"${title ? ` title="${esc(title)}"` : ''}>${esc(txt)}</span>`;
+const broken = (txt, title) => `<span class="bl" role="alert"${title ? ` title="${esc(title)}"` : ''}>${esc(txt)}</span>`;
+
+// The initiative a branch names, and the record behind it — four cases now, all of them stated. A
 // branch with no record is NOT an initiative with a missing file; it is a branch, and the row says
-// so rather than inventing an id (R2).
+// so rather than inventing an id (R2). A workspace with no branch is either an ordinary folder that
+// is not a repository (quiet) or a git read that failed (a fault) — never the same word for both.
+// A ROW ALWAYS HAS AN IDENTITY. The first version used this label for both the row's name and its
+// condition, so a plain folder rendered as a row literally titled `branch unreadable` — a row with
+// no name at all, which is unfindable in a tree of them. The name is what the row IS; the condition
+// is what is true of it, and it belongs on the second line with the other derived facts.
 function initiativeOf(w) {
   const br = w.branch;
-  if (!br) return { kind: 'nobranch', label: w.branch_error ? 'branch unreadable' : 'detached HEAD', id: null };
+  if (!br) {
+    if (!w.branch_error) return { kind: 'detached', label: w.name, id: null };
+    // 'no-git' is not a failure to report a branch; it is a folder that HAS no branch. The message
+    // is branchInfo's own ("not a git repository") — this renderer does not compose its own prose.
+    if (w.branch_code === 'no-git') return { kind: 'nogit', label: w.name, id: null };
+    return { kind: 'branchbroken', label: w.name, id: null, condition: w.branch_error };
+  }
   const m = /^initiative\/(.+)$/.exec(br);
   if (!m) return { kind: 'branch', label: br, id: null };
   const id = m[1];
@@ -283,12 +315,15 @@ function boardRow(w, id) {
 // something needs the PM. Rows without a signal collapse to a count (R6). The PM's own toggle always
 // wins — `state.openTrees` holds it, and it is re-applied after every render for the same reason
 // `state.openHarness` is: this pane is rebuilt by innerHTML on every push.
+// R7 — EXPANSION MUST BE EARNED. Signals divide in two, and the first version conflated them:
+//   * a signal about the TREE (a needs count, a blocker) belongs ON the row and is already rendered
+//     there — opening the container shows the PM nothing they cannot already see;
+//   * a signal about a SESSION is only visible once the container is open, so it earns the open.
+// Conflating them is why a repository with one queued need and no sessions expanded to reveal a
+// lone "＋ session here" button. A row that opens onto nothing teaches you to distrust its glyphs.
 function treeHasSignal(w) {
   const mine = state.sessions.filter((s) => s.ws === w.id);
-  if (state.needsByWs[w.id] && state.needsByWs[w.id].count) return true;
-  if (state.needsByWs[w.id] && state.needsByWs[w.id].error) return true;
-  const init = initiativeOf(w);
-  if (init.row && init.row.blockers && init.row.blockers.length) return true;
+  if (!mine.length) return false;                 // nothing to reveal, so nothing to open for
   return mine.some((s) => {
     const shown = stateLabel(s).shown;
     return shown === 'working' || shown === 'blocked' || shown === 'exited';
@@ -340,6 +375,18 @@ function renderTree() {
   }).join('');
   host.innerHTML = html || `<div class="empty">No repositories — run <b>pmos</b> inside one.</div>`;
   host.querySelectorAll('[data-pick]').forEach((b) => b.onclick = () => selectWorkspace(b.dataset.pick));
+  // R6 — select the tree AND open the composer against it. Deliberately NOT awaited: selectWorkspace
+  // ends on four network reads (library · needs · branch · worktrees), and making the composer wait
+  // on them puts a variable delay between a click and any visible response — the failure mode the
+  // board cache was built to remove elsewhere. `state.wsId` is assigned synchronously at the top of
+  // selectWorkspace, so the form opens naming the RIGHT tree immediately; loadBranch() refills the
+  // branch picker when it lands, which is the same path the ＋ button already relies on.
+  host.querySelectorAll('[data-start]').forEach((b) => b.onclick = (e) => {
+    e.stopPropagation();
+    const p = selectWorkspace(b.dataset.start);
+    openNewForm();
+    p.then(() => { if (!$('newForm').hidden) renderNewTarget(); });
+  });
   host.querySelectorAll('[data-repo-pick]').forEach((b) => b.onclick = () => openRepoDetail(b.dataset.repoPick));
   host.querySelectorAll('[data-forget]').forEach((b) => b.onclick = (e) => { e.stopPropagation(); forgetWorkspace(b.dataset.forget); });
   host.querySelectorAll('[data-toggle]').forEach((b) => b.onclick = (e) => {
@@ -388,11 +435,30 @@ function treeRow(w, g) {
   } else if (board && board.pending) {
     wf = `<span class="wf"><span class="drv">deriving the ladder…</span></span>`;
   } else if (board && board.ok === false) {
-    wf = `<span class="wf"><span class="bl">ladder unreadable</span></span>`;
+    // The one case that stays RED. The engine's own message says which fault it is — an install
+    // that carries no engine reads differently from one whose engine threw — so it is carried
+    // through as the tooltip rather than compressed into two words (incident
+    // kit-workflow-engine-missing: "ladder unreadable" was every adopter's entire experience of
+    // this surface, and it named neither the cause nor anything the PM could act on).
+    wf = `<span class="wf">${broken('ladder unreadable', board.error || '')}</span>`;
+  } else if (board && board.ok === true && board.empty === true) {
+    // VERIFIED ABSENT, and the sentence is about the REPOSITORY, not the branch: the engine read
+    // this repo successfully and it has no initiative records. Pointing the workspace at an
+    // ordinary repo is a supported thing to do, so this is the calm common case, not a defect.
+    wf = `<span class="wf">${absent('no initiatives yet', 'this repository has no planning/initiatives/ records — the workspace read it successfully')}</span>`;
   } else if (init.kind === 'norecord') {
-    wf = `<span class="wf"><span class="drv">no initiative record</span></span>`;
+    // An initiative BRANCH whose record is missing — genuinely a gap in the repo, but not a failed
+    // read, so it stays quiet and says precisely which of the two it is.
+    wf = `<span class="wf">${absent('no record for this branch', `the branch names initiative "${init.id}" but planning/initiatives/${init.id}.md is not there`)}</span>`;
   } else if (init.kind === 'branch') {
-    wf = `<span class="wf"><span class="drv">no initiative</span></span>`;
+    wf = `<span class="wf">${absent('not an initiative branch', `"${w.branch}" does not match initiative/<id>, so no ladder is derived for it`)}</span>`;
+  } else if (init.kind === 'nogit') {
+    wf = `<span class="wf">${absent('not a git repository', 'an ordinary folder — sessions run here, but nothing git-derived applies to it')}</span>`;
+  } else if (init.kind === 'branchbroken') {
+    // The other half of the split: git IS here and the read FAILED. This one keeps the alarm.
+    wf = `<span class="wf">${broken('branch unreadable', init.condition || '')}</span>`;
+  } else if (init.kind === 'detached') {
+    wf = `<span class="wf">${absent('detached HEAD', 'no branch is checked out, so no initiative is derived from one')}</span>`;
   }
   // the attribution line: which branch this ladder came from, and as of when
   const stamp = board && board.as_of ? new Date(board.as_of).toLocaleTimeString() : null;
@@ -400,8 +466,11 @@ function treeRow(w, g) {
     ? `<span class="attrib">derived on <b>${esc(w.branch || '?')}</b>${stamp ? ` · as of ${esc(stamp)}` : ''}${board && board.stale ? ' · refreshing' : ''}</span>`
     : '';
 
+  // R6 — the verb is performed. This used to call selectWorkspace() and stop, and its own tooltip
+  // admitted it ("select this tree, THEN start a session"). `data-start` selects the tree AND opens
+  // the composer against it, focused.
   const sessHtml = open ? mine.map((s) => sessionRow(s)).join('')
-    + `<button class="tree-new" data-pick="${esc(w.id)}" title="select this tree, then start a session">＋ session here</button>`
+    + `<button class="tree-new" data-start="${esc(w.id)}" title="start a session in ${esc(w.name)}">＋ session here</button>`
     : '';
   const collapsed = !open && mine.length
     ? `<span class="rollup">${mine.length} session${mine.length === 1 ? '' : 's'}${live ? '' : ' · all exited'}</span>` : '';
@@ -413,9 +482,9 @@ function treeRow(w, g) {
       <button class="tr" data-pick="${esc(w.id)}" aria-current="${cur}" title="${esc(w.root)}">
         <span class="r1"><span class="g" aria-hidden="true">${TREE_GLYPH[gl] || '·'}</span>
           <span class="nm">${esc(init.label)}</span>
-          ${w.home ? '<span class="tag">home</span>' : ''}
+          ${w.home ? `<span class="tag" title="the folder pmos was launched in — it is always hosted and cannot be removed">home</span>` : ''}
           <span class="dir">${esc(w.name === g.name ? 'main tree' : w.name)}</span></span>
-        <span class="r2">${wf}${n && n.count ? `<span class="needs-n">${n.count} need you</span>` : ''}${n && n.error ? '<span class="bl">needs unreadable</span>' : ''}${collapsed}</span>
+        <span class="r2">${wf}${n && n.count ? `<span class="needs-n">${n.count} need you</span>` : ''}${n && n.error ? broken('needs unreadable', n.error) : ''}${collapsed}</span>
         ${attrib}
       </button>
       ${w.home ? '' : `<button class="forget" data-forget="${esc(w.id)}" aria-label="Stop hosting ${esc(w.name)}" title="${live ? 'end its sessions first' : 'stop hosting this repo (the repo is untouched)'}">✕</button>`}
@@ -2094,10 +2163,34 @@ function resolveDocPath(ctx, u) {
 }
 
 // ── new session: name it, pick its branch, before it starts ──
+/* R5 — "HERE" MUST HAVE A VISIBLE REFERENT.
+ *
+ * The composer acts on `state.wsId` and always did. That was legible when it lived underneath a
+ * single selected workspace pane; once the sidebar became one tree showing every repository at
+ * once, "run an agent here" named nothing on screen. This does not change WHAT it acts on (that
+ * would be a behaviour change — PRD assumption A3); it makes the target sayable before the click.
+ *
+ * Called from three places, because the target changes without the form being reopened: on open, on
+ * every workspace selection, and on every workspace push (a rename or a checkout moves the branch). */
+function newTargetText() {
+  const w = state.workspaces.find((x) => x.id === state.wsId);
+  if (!w) return { text: 'no tree selected — choose one below first', none: true };
+  const init = initiativeOf(w);
+  const where = init.kind === 'nogit' ? 'a plain folder' : (w.branch ? `on ${w.branch}` : 'no branch checked out');
+  return { text: `in ${w.name} · ${where}`, none: false };
+}
+function renderNewTarget() {
+  const el = $('newWhere');
+  if (!el) return;
+  const t = newTargetText();
+  el.textContent = t.text;
+  el.dataset.none = t.none ? '1' : '0';
+}
 function openNewForm() {
   const w = state.workspaces.find((x) => x.id === state.wsId);
   $('newForm').hidden = false;
   $('newBtn').setAttribute('aria-expanded', 'true');
+  renderNewTarget();
   // pre-filled but editable — a default that reads better than "shell" in a list of shells
   const n = mySessions().length + 1;
   $('newName').value = `${w ? w.name : 'session'} ${n}`;

package/workspace/public/index.html

@@ -68,12 +68,17 @@
         <div class="cap">
           <span class="grip" id="sideGrip" data-pane="side" role="button" tabindex="0"
             aria-label="Move the sidebar" title="Move this column">⠿</span>
-          <button class="fold" id="wsFold" data-fold="ws" aria-expanded="true" title="Hide the work tree"><span class="chev" aria-hidden="true">▾</span>work</button>
+          <!-- R8: the pane states its structure. It was called `work` — the least informative word
+               available for a tree of repositories, their working trees, and their sessions. -->
+          <button class="fold" id="wsFold" data-fold="ws" aria-expanded="true" title="Hide the repositories, their working trees and their sessions"><span class="chev" aria-hidden="true">▾</span>repos &amp; sessions</button>
           <span class="ct" id="needCount"></span>
           <button class="mini" id="addWsBtn" aria-expanded="false" title="Add a repository">＋</button></div>
         <div class="pane-body">
           <button class="newsess" id="newBtn" aria-expanded="false"><i>＋</i> new session — run an agent here</button>
           <form class="miniform" id="newForm" hidden>
+            <!-- R5: "here" gets a visible referent. The composer has always acted on the selected
+                 tree; with every repository on screen at once, nothing said which that was. -->
+            <p class="where" id="newWhere"></p>
             <label class="lbl" for="newName">name this session</label>
             <input id="newName" type="text" placeholder="e.g. jira-sync build" aria-label="Session name" autocomplete="off" spellcheck="false" />
             <div class="seg" role="radiogroup" aria-label="Agent to run" id="newAgents">

package/workspace/public/styles.css

@@ -1371,7 +1371,12 @@ line-height:1.35;cursor:pointer}
 .tr .wf .lane{color:var(--muted-foreground)}
 .tr .wf .stg{color:var(--brand)}
 .tr .wf .nx{color:var(--muted-foreground)}
+/* THE THREE-VALUED VOCABULARY (R2). Two renderings for three facts means one is always mislabelled
+   — which is how an ordinary folder came to render as an alarm on the same surface that uses
+   --destructive for a corrupt state queue. `.bl` keeps the alarm; `.gone` is the quiet, specific
+   "the read succeeded and there is nothing here"; a value is styled as neither. */
 .tr .wf .bl,.tr .r2 .bl{color:var(--destructive)}
+.tr .wf .gone,.tr .r2 .gone{color:var(--muted-foreground);opacity:.8}
 .tr .wf .drv{color:var(--muted-foreground);font-style:italic}
 .tr .needs-n{color:var(--warning)}
 .tr .rollup{color:var(--muted-foreground)}
@@ -1384,6 +1389,11 @@ line-height:1.35;cursor:pointer}
   border:1px dashed var(--border);border-radius:var(--radius-sm);color:var(--muted-foreground);
   font:inherit;font-size:var(--text-2xs);cursor:pointer;text-align:left}
 .tree-new:hover{color:var(--foreground);border-color:var(--input)}
+/* R5 — the composer's target. "run an agent here" named nothing once every repository was on
+   screen at once; this is the referent, and it updates on every selection change. */
+.miniform .where{font-family:var(--mono);font-size:var(--text-2xs);color:var(--muted-foreground);
+  margin:0 0 6px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.miniform .where[data-none="1"]{color:var(--warning)}
 .cap .ct[data-bad="1"]{color:var(--destructive)}
 
 /* ── The rail's initiative dossier (R7·R8·R9) ────────────────────────────────────────────────── */

package/workspace/server.js

@@ -229,7 +229,7 @@ function repoIdentity(root) {
   const hit = repoKeyCache.get(root);
   const now = Date.now();
   if (hit && now - hit.at < REPO_KEY_TTL_MS) return hit;
-  let key = root, name = path.basename(root), branch = null, branchError = null;
+  let key = root, name = path.basename(root), branch = null, branchError = null, branchCode = null;
   try {
     const trees = gitInfo.worktrees(root);
     if (trees.length && trees[0].dir) { key = path.resolve(trees[0].dir); name = path.basename(key); }
@@ -237,9 +237,16 @@ function repoIdentity(root) {
   try {
     const bi = gitInfo.branchInfo(root);
     if (bi.ok) branch = bi.detached ? null : bi.current;
-    else branchError = bi.error || 'branch could not be read';
-  } catch { branchError = 'branch could not be read'; }
-  const val = { at: now, key, name, branch, branchError };
+    // R1/A2 — carry the CODE and the MESSAGE, not a boolean. branchInfo already separates the two
+    // failures and says so in its own comment: `no-git` is an ordinary folder and "deserves no
+    // alarm", `git-error` is something the PM may want to look at. Keeping only a truthy string here
+    // is what let the client render both as `branch unreadable` — an alarm on the normal case, on
+    // the same surface that uses red for a corrupt state queue. The renderer must not re-derive
+    // meaning from a boolean; a second place that decides what a failure MEANS is how the first
+    // one drifts.
+    else { branchError = bi.error || 'branch could not be read'; branchCode = bi.code || 'git-error'; }
+  } catch { branchError = 'branch could not be read'; branchCode = 'git-error'; }
+  const val = { at: now, key, name, branch, branchError, branchCode };
   repoKeyCache.set(root, val);
   return val;
 }
@@ -250,8 +257,11 @@ function wsList() {
       id: w.id, name: w.name, root: w.root, home: HOME_ENABLED && w.root === SELF_ROOT,
       shape: wsShape(w.root), addedAt: w.addedAt,
       sessions: [...sessions.values()].filter((s) => s.ws === w.id).length,
-      // the repository this working tree belongs to, and the branch it is on
-      repo_key: rid.key, repo_name: rid.name, branch: rid.branch, branch_error: rid.branchError,
+      // the repository this working tree belongs to, and the branch it is on. `branch_code`
+      // distinguishes an ordinary non-repo folder ('no-git') from a real git fault ('git-error') —
+      // the client renders the first quietly and the second as a fault (R1/R2).
+      repo_key: rid.key, repo_name: rid.name, branch: rid.branch,
+      branch_error: rid.branchError, branch_code: rid.branchCode,
     };
   });
 }
@@ -1018,7 +1028,18 @@ function transcriptHarness(s) {
     s.txFoundAt = now;
   }
   const found = s.txFound;
-  if (found.missing) return { missing: { all: found.missing } };
+  if (found.missing) {
+    // R4 — VERIFIED ABSENT IS NOT A FAILED SEARCH. A `shell` pane is walked for a descendant claude
+    // because the PM often starts one there; when none is running, findTranscript's answer ("the CLI
+    // wrote no session record") describes the SEARCH, and reads as a fault on a pane that is doing
+    // exactly what a shell does. Nothing is wrong, nothing is missing, and there is nothing for the
+    // PM to fix — so say what is true and what would change it. Every other reason (a record that is
+    // unreadable, one belonging to another workspace) IS a fault and keeps its own words.
+    if (s.agent === 'shell' && /wrote no session record/.test(found.missing)) {
+      return { missing: { all: 'no agent is running in this shell — start one here and its harness appears', calm: true } };
+    }
+    return { missing: { all: found.missing } };
+  }
   let stamp = null;
   try { const st = fs.statSync(found.file); stamp = `${st.size}:${st.mtimeMs}`; } catch {}
   if (s.tx && s.txStamp === stamp) return s.tx;
@@ -2879,6 +2900,10 @@ if (require.main === module) {
 }
 module.exports = { server, spawnSession, removeSession, renameSession, sessions, libraryTree, readTextDoc,
   registerWorkspace, forgetWorkspace, workspaces, library, initiativeIndex, fsList,
+  // R1 — exported so the suite can assert the CARRY-THROUGH: branchInfo separates an ordinary
+  // non-repo folder from a real git fault, and the whole legibility defect was that distinction
+  // being dropped one layer above it.
+  repoIdentity, wsList,
   // exported so the suite can assert the D08 invariant end-to-end: the harness parsers consume
   // scrubbed text, so a secret printed into scrollback must not survive into a rendered value.
   scrub, harnessOf,