create-pmos 0.14.0 → 0.16.0

package/workspace/lib/layout.js

@@ -6,7 +6,7 @@
  * so a layout the client can produce and a layout the server will store can never disagree.
  *
  * A layout is a NAMED STATE TUPLE. The grid template is COMPUTED from it (gridFor) rather than
- * hand-written per layout, because the twelve side×reader combinations are exactly where a
+ * hand-written per layout, because that is exactly where a
  * hand-written template drifts: a column count that no longer matches its area row produces an
  * unusable window, and the PM's live agent sessions are inside it.
  *
@@ -24,24 +24,41 @@
   else root.PMOSLayout = api;
 })(typeof self !== 'undefined' ? self : this, function () {
 
+  /* workspace-viewer-column — `reader` is RETIRED from the tuple.
+   *
+   * It used to hold four positions and decided where a document rendered. Documents, images and
+   * the summoned surfaces now open as tabs in the terminal column, so there is no longer a pane to
+   * position: `#paneDoc`, `#railSplit` and `libSplit` went with it, and `.rail` is the detail panel
+   * alone. Keeping the slot and merely emptying it was the alternative and is the worse one — it
+   * would leave document-shaped content two possible homes and no rule for which.
+   *
+   * What survives is the DETAIL PANEL's column, which still needs a width and keeps its drag
+   * handle — `readW` is renamed `panelW` and old values fall back to it, since it sized the same
+   * column. What does not survive is its POSITION: the panel now always sits between the structure
+   * column and the terminal, because the four positions existed to place a document.
+   *
+   * So the tuple is `{side, split, sideW, panelW, folds}` rather than seven fields.
+   */
   const SIDE = ['left', 'right', 'off'];
-  const READER = ['left', 'right', 'bottom', 'off'];      // FOUR positions (R1) — every position
-  const SPLIT = ['off', 'on'];                            // the state can hold has a control
-  const FOLD_KEYS = ['ws', 'sess', 'lib', 'doc'];
+  const SPLIT = ['off', 'on'];
+  // `doc` retired with the pane it folded. `sess` was already retired (R13) and is likewise ignored
+  // rather than migrated — a stored value for either resolves harmlessly through sanitize.
+  const FOLD_KEYS = ['ws', 'lib'];
+  const RETIRED_FOLD_KEYS = ['sess', 'doc'];
 
   const SIDE_MIN = 160, SIDE_MAX = 520;
-  const READ_MIN = 280, READ_MAX = 1000;
-  const LIB_MIN = 15, LIB_MAX = 80;                       // the library/document divider, percent
-  const BOTTOM_H = 300;                                   // the reader's height when docked bottom
-  const LIB_DEFAULT = 46;
+  const PANEL_MIN = 280, PANEL_MAX = 1000;                // the detail panel's width, still draggable
 
-  // `review` is byte-for-byte the arrangement that shipped before this feature (R2): a PM who
-  // never opens the layout control must see no change at all.
+  // `review` is the DEFAULT — the arrangement a PM who never opens the layout control sees.
+  // With the reader retired, the four stock layouts differ in the two axes that remain: whether the
+  // structure column is present, which side it sits on, and whether the terminal is split. That is
+  // fewer axes than before and they are kept genuinely distinct rather than padded back out to four
+  // by inventing differences the PM would not feel.
   const STOCK = [
-    { id: 'focus',   name: 'focus',   key: 1, side: 'off',  reader: 'off',    split: 'off', sideW: 262, readW: 400, libSplit: LIB_DEFAULT },
-    { id: 'read',    name: 'read',    key: 2, side: 'left', reader: 'left',   split: 'off', sideW: 214, readW: 760, libSplit: LIB_DEFAULT },
-    { id: 'compare', name: 'compare', key: 3, side: 'left', reader: 'off',    split: 'on',  sideW: 214, readW: 400, libSplit: LIB_DEFAULT },
-    { id: 'review',  name: 'review',  key: 4, side: 'left', reader: 'right',  split: 'off', sideW: 262, readW: 400, libSplit: LIB_DEFAULT },
+    { id: 'focus',   name: 'focus',   key: 1, side: 'off',   split: 'off', sideW: 262, panelW: 460 },
+    { id: 'read',    name: 'read',    key: 2, side: 'left',  split: 'off', sideW: 214, panelW: 760 },
+    { id: 'compare', name: 'compare', key: 3, side: 'left',  split: 'on',  sideW: 214, panelW: 420 },
+    { id: 'review',  name: 'review',  key: 4, side: 'left',  split: 'off', sideW: 280, panelW: 560 },
   ];
   const DEFAULT_ID = 'review';
   const STOCK_IDS = STOCK.map((l) => l.id);
@@ -54,7 +71,7 @@
     return Number.isFinite(n) ? n : fallback;
   };
 
-  function defaultFolds() { return { ws: true, sess: true, lib: true, doc: true }; }
+  function defaultFolds() { return { ws: true, lib: true }; }
   function folds(v) {
     const out = defaultFolds();
     if (v && typeof v === 'object') for (const k of FOLD_KEYS) if (typeof v[k] === 'boolean') out[k] = v[k];
@@ -84,15 +101,19 @@
       name: stock ? base.name : name,                       // stock names are not editable (R5)
       key: stock ? base.key : null,                         // ⌃1–⌃4 belong to the stock four
       side: oneOf(r.side, SIDE, base ? base.side : 'left'),
-      reader: oneOf(r.reader, READER, base ? base.reader : 'right'),
       split: oneOf(r.split, SPLIT, base ? base.split : 'off'),
       sideW: Math.round(clamp(num(r.sideW, base ? base.sideW : 262), SIDE_MIN, SIDE_MAX)),
-      readW: Math.round(clamp(num(r.readW, base ? base.readW : 400), READ_MIN, READ_MAX)),
-      // the library/document divider. It lives IN the tuple rather than in localStorage because R8
-      // promises to carry it across the upgrade and dimension 1 counts it as "nothing lost" — a
-      // global client key can satisfy neither: it is not per-workspace, and it goes on being read
-      // from the pre-feature store on every boot, which R8 explicitly forbids.
-      libSplit: Math.round(clamp(num(r.libSplit, base ? base.libSplit : LIB_DEFAULT), LIB_MIN, LIB_MAX) * 10) / 10,
+      // The detail panel keeps a width and keeps its drag handle. A layout stored before this
+      // change has no `panelW`, but it does have the `readW` that used to size the same column —
+      // so that is what it falls back to, and the PM's tuning survives the rename instead of
+      // snapping to a default. This is the one legacy field genuinely worth carrying.
+      panelW: Math.round(clamp(num(r.panelW, num(r.readW, base ? base.panelW : 560)), PANEL_MIN, PANEL_MAX)),
+      // `reader`, `readW` and `libSplit` are DROPPED rather than carried. Every layout persisted
+      // before workspace-viewer-column still holds all three, and they arrive here on every boot in
+      // a live workspace — so the contract that matters is that reading them is harmless, which it
+      // is: unknown keys on `r` are simply not copied out. Dropping is deliberate and not silent —
+      // a value for a pane that no longer exists cannot be honoured, and carrying it forward would
+      // let a later reader resurrect a pane the app can no longer render.
       folds: folds(r.folds),
       lastUsedAt: Math.max(0, Math.round(num(r.lastUsedAt, 0))),
     };
@@ -130,19 +151,17 @@
   /* The computed grid. Returns {columns, rows, areas} as CSS strings.
      INVARIANT: every area row names exactly as many cells as `columns` has tracks. */
   function gridFor(l) {
-    const S = l.sideW + 'px', R = l.readW + 'px';
-    if (l.reader === 'bottom') {
-      const rows = 'minmax(0,1fr) ' + BOTTOM_H + 'px';
-      if (l.side === 'left')  return { columns: S + ' minmax(0,1fr)', rows, areas: '"side term" "side read"' };
-      if (l.side === 'right') return { columns: 'minmax(0,1fr) ' + S, rows, areas: '"term side" "read side"' };
-      return { columns: 'minmax(0,1fr)', rows, areas: '"term" "read"' };
-    }
+    const S = l.sideW + 'px', P = l.panelW + 'px';
+    // The detail panel is no longer independently positionable: it always sits between the
+    // structure column and the terminal, because that is the order the work flows in — pick the
+    // initiative, read its state, act on it. The four positions it used to have existed to place a
+    // DOCUMENT, and documents are tabs in the terminal column now. Hiding the panel is the column
+    // collapse (a 36px labelled rail), which is client state rather than part of the arrangement.
     const cols = [], names = [];
-    if (l.side === 'left')   { cols.push(S); names.push('side'); }
-    if (l.reader === 'left') { cols.push(R); names.push('read'); }
+    if (l.side === 'left')  { cols.push(S); names.push('side'); }
+    cols.push(P); names.push('read');
     cols.push('minmax(0,1fr)'); names.push('term');
-    if (l.reader === 'right'){ cols.push(R); names.push('read'); }
-    if (l.side === 'right')  { cols.push(S); names.push('side'); }
+    if (l.side === 'right') { cols.push(S); names.push('side'); }
     return { columns: cols.join(' '), rows: 'minmax(0,1fr)', areas: '"' + names.join(' ') + '"' };
   }
 
@@ -156,28 +175,31 @@
      The property item 4 actually names — the control that un-hides a pane is itself always
      reachable — is a fact about the DOM (the chip lives in `.bar`, a grid sibling of `#bodyGrid`,
      and the position controls in `.lay-pos` can always restore a pane), and it is asserted where
-     it can genuinely fail: ui-test.js walks all twelve side × reader states in a real engine. */
+     it can genuinely fail: ui-test.js walks every remaining arrangement in a real engine. */
   function hasEscape(l) {
     return gridFor(l).areas.indexOf('term') !== -1;
   }
 
   /* R8 — carry the pre-feature client keys into this workspace's `review` so nobody's tuning is
-     lost on upgrade. Reads the five localStorage values the shipped app wrote:
+     lost on upgrade. It read five localStorage values the shipped app wrote:
      rail(on|off) railw(<n>px) libsplit(<n>%) fold-lib(on|off) fold-doc(on|off).
-     It formerly said "five" and read four — `libsplit` was collected by the caller and dropped
-     here, so R8's promise was false for it and the pre-feature key went on being read at every
-     boot. Review-Gate finding: the comment was the spec, and the code disagreed with it. */
+
+     THREE OF THE FIVE NO LONGER HAVE ANYWHERE TO GO, and that is stated rather than quietly
+     dropped: `rail: off` positioned a pane that is now always a column (hiding it is the column
+     collapse, which is client state and not part of an arrangement); `libsplit` divided a rail that
+     no longer has two halves; `fold-doc` folded `#paneDoc`, which no longer exists. Carrying any of
+     them would mean writing a value no reader can honour.
+
+     `railw` still has a real destination — it sized the same column `panelW` now sizes — so it is
+     the one width that survives, and `fold-lib` still folds the pane it always folded. A PM
+     upgrading from the pre-feature build keeps their column width and their fold; they lose a
+     reader position for a reader that is gone. */
   function migrateLegacy(legacy) {
     const g = (k) => (legacy && typeof legacy === 'object' ? legacy[k] : null);
     const review = stockLayout(DEFAULT_ID);
-    const railOff = g('rail') === 'off';
-    if (railOff) review.reader = 'off';
     const w = num(String(g('railw') || '').replace('px', ''), null);
-    if (w !== null) review.readW = Math.round(clamp(w, READ_MIN, READ_MAX));
-    const ls = num(String(g('libsplit') || '').replace('%', ''), null);
-    if (ls !== null) review.libSplit = Math.round(clamp(ls, LIB_MIN, LIB_MAX) * 10) / 10;
+    if (w !== null) review.panelW = Math.round(clamp(w, PANEL_MIN, PANEL_MAX));
     if (g('fold-lib') === 'off') review.folds.lib = false;
-    if (g('fold-doc') === 'off') review.folds.doc = false;
     const layouts = stockLayouts().map((l) => (l.id === DEFAULT_ID ? review : l));
     return { layouts, currentId: DEFAULT_ID };
   }
@@ -198,8 +220,8 @@
   }
 
   return {
-    SIDE, READER, SPLIT, FOLD_KEYS, STOCK_IDS, DEFAULT_ID,
-    SIDE_MIN, SIDE_MAX, READ_MIN, READ_MAX, LIB_MIN, LIB_MAX, LIB_DEFAULT, BOTTOM_H,
+    SIDE, SPLIT, FOLD_KEYS, RETIRED_FOLD_KEYS, STOCK_IDS, DEFAULT_ID,
+    SIDE_MIN, SIDE_MAX, PANEL_MIN, PANEL_MAX,
     isStock, stockLayout, stockLayouts, layout, sanitize, gridFor, hasEscape, migrateLegacy,
     loadAction,
   };

package/workspace/lib/mobile-nav.js

@@ -0,0 +1,157 @@
+/* mobile-nav — the phone surface's navigation reducer (workspace-mobile-surface).
+ *
+ * One source of truth for "which screen am I on", used on BOTH sides:
+ *   - the browser loads it as /lib/mobile-nav.js before app.js (window.PMOSMobileNav)
+ *   - test.js requires it, so the whole domain is walkable in node without a browser
+ * exactly as lib/layout.js is. It was written inline in app.js and moved here because the rubric
+ * asks for a pure module and because a reducer that cannot be unit-tested is one whose exclusivity
+ * guarantee is only ever checked by eye.
+ *
+ * DOM-FREE ON PURPOSE. Every function takes a nav state and returns a new one; none touches an
+ * element, a media query, or the app's `state`. That is what makes the four properties below
+ * decidable without a browser:
+ *   P1  exactly one column is shown for any screen — `column` is a function of `kind` alone
+ *   P2  every MODES key has a phone path — the map is iterated, never a literal list
+ *   P3  back never exits the app and never unwinds into another destination
+ *   P4  choosing a destination resets it to its root
+ *
+ * The screen model:
+ *   { dest, kind, mode, id, dk, title, column }
+ *     dest    one of DESTS — which destination this screen belongs to
+ *     kind    'list' | 'detail' | 'terminal' | 'doc' | 'more'
+ *     mode    a MODES key, for kind 'list'
+ *     id      the detail id / session id / viewer id
+ *     dk      the DETAIL kind, for kind 'detail'
+ *     title   only for 'terminal' and 'doc', where the name is not derivable
+ *     column  'side' | 'term' | 'rail' — determined by `kind` and by nothing else
+ *
+ * `column` is the whole of the exclusivity guarantee: the stylesheet shows exactly one of the three
+ * column nodes per value, so P1 is a property of the CSS rather than something this reducer has to
+ * remember to enforce. The columns are never re-parented and never rebuilt, which is what makes the
+ * xterm instance and its PTY socket survive a push, a pop and a destination switch structurally.
+ */
+'use strict';
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSMobileNav = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+// What a LIST screen is called, keyed by mode. This mirrors `MODES[].title` in app.js, and the
+// mirror is deliberate rather than lazy: `titleOf` used to read app.js's `MODE_BY_K` directly,
+// which works in a browser (one global scope) and throws `ReferenceError` the moment the module is
+// required in node — for `kind:'list'`, the root of four of the five destinations. Nothing was red,
+// because nothing called it outside a browser; the header two lines below claimed the whole domain
+// was walkable in node, and it was not. A module that reaches back into its caller for a lookup
+// table is not pure, and the fix for that is to hold the table, not to keep reaching.
+// The drift risk a mirror creates is paid for in the suite: MOBNAV-P6 iterates app.js's own MODES
+// against this map, so a mode added or retitled there and forgotten here fails rather than
+// silently renders a key where a title belongs.
+const MODE_TITLE = {
+  product: 'initiatives', scheduled: 'scheduled tasks', workflow: 'workflows', skills: 'skills',
+  knowledge: 'knowledge', agent: 'agents', memory: 'memory',
+};
+// What a DETAIL screen is called. It moved here with the reducer, for the same reason.
+// The second block is the four-panel surface's `detail.kind` vocabulary (pm/app.js's DETAIL_TITLE).
+// It is ADDED rather than substituted: the first block is what the retired surface pushes and the
+// two overlap on every key they share, so one map titles a detail screen coming from either. A
+// missing key here is not a crash — `titleOf` falls back to 'detail' — it is a phone header that
+// says nothing, which is why the set is written down rather than left to the fallback.
+const DETAIL_TITLE = {
+  initiative: 'initiative', repo: 'repository', flow: 'workflow', sched: 'scheduled task',
+  skill: 'skill', know: 'knowledge', agent: 'agent', mem: 'memory',
+  ingest: 'ingest proposal', profiles: 'profiles', connections: 'connections',
+  init: 'initiative', prof: 'claude profile', intg: 'connection',
+  addprod: 'add repository', new: 'file new',
+};
+
+const MOBILE_DESTS = ['board', 'scheduled', 'agents', 'memory', 'more'];
+// Every MODES key has an entry. The suite ITERATES `MODES` against this map rather than a literal
+// list, so adding a mode without giving it a phone path fails the suite instead of going silently
+// unreachable — which is the failure P2 exists to catch.
+const MOBILE_DEST = { product: 'board', scheduled: 'scheduled', agent: 'agents', memory: 'memory',
+  workflow: 'more', skills: 'more', knowledge: 'more' };
+const MOBILE_ROOT = {
+  board: { kind: 'list', mode: 'product' },
+  scheduled: { kind: 'list', mode: 'scheduled' },
+  agents: { kind: 'list', mode: 'agent' },
+  memory: { kind: 'list', mode: 'memory' },
+  more: { kind: 'more', mode: null },
+};
+// kind → column. There is no second input, and no screen may carry a column its kind does not give.
+const MOBILE_COLUMN = { list: 'side', more: 'side', detail: 'rail', terminal: 'term', doc: 'term' };
+function mobColumnOf(kind) { return MOBILE_COLUMN[kind] || 'side'; }
+
+/* kind → PANEL INDEX, for the four-panel surface (public/pm/).
+ *
+ * WHY THIS EXISTS ALONGSIDE `column`, RATHER THAN REPLACING IT. `column` names one of the three
+ * columns of the retired `public/app.js` layout, and MOBNAV-P1 pins it to exactly those three
+ * values. The surface that ships now has FOUR panels — repositories · mode list · detail · tabs —
+ * and two of the old `side` screens belong to DIFFERENT panels there: a `list` screen is panel 2
+ * (the mode list) while a `more` screen is panel 1, which is the structure/settings panel and is
+ * therefore the phone's "more" destination in the four-panel design.
+ *
+ * So this is an ADDITIVE widening, not an edit: `columnOf` is untouched and still describes the
+ * three-column layout truthfully for the surface that owns it, and `panelOf` describes the
+ * four-panel one. Both are pure functions of `kind` alone, so the exclusivity guarantee — one
+ * visible surface per screen — is the same property stated against a different layout. Putting it
+ * HERE rather than in pm/mobile.js keeps a single node-walkable source of truth for "which surface
+ * does this screen show", which is the whole reason the reducer was pulled out of app.js.
+ */
+const MOBILE_PANEL = { more: 0, list: 1, detail: 2, terminal: 3, doc: 3 };
+function mobPanelOf(kind) {
+  return Object.prototype.hasOwnProperty.call(MOBILE_PANEL, kind) ? MOBILE_PANEL[kind] : 1;
+}
+function mobDestForMode(k) { return MOBILE_DEST[k] || null; }
+// Complete a partial screen. The column is derived, never passed in, so a caller cannot put a
+// detail on the terminal column by writing it down.
+function mobScreen(s) {
+  const kind = (s && s.kind) || 'list';
+  return { dest: (s && s.dest) || 'board', kind, mode: (s && s.mode) || null,
+    id: (s && s.id) || null, dk: (s && s.dk) || null, title: (s && s.title) || null,
+    column: mobColumnOf(kind) };
+}
+function mobRootOf(dest) {
+  const r = MOBILE_ROOT[dest] || MOBILE_ROOT.board;
+  return mobScreen({ dest: MOBILE_ROOT[dest] ? dest : 'board', kind: r.kind, mode: r.mode });
+}
+/* The title map. `list` and `more` derive; `detail` reads DETAIL_TITLE (declared far below — this
+ * is only ever called at runtime, long after that const has evaluated); `terminal` and `doc` carry
+ * a title because a session's name and a document's name are not derivable from a screen. */
+function mobTitleOf(s) {
+  if (!s) return '';
+  if (s.kind === 'list') return MODE_TITLE[s.mode] || String(s.mode || '');
+  if (s.kind === 'more') return 'more';
+  if (s.kind === 'detail') return DETAIL_TITLE[s.dk] || 'detail';
+  return s.title || String(s.id || '');
+}
+function mobNavInit(dest) { return { dest: MOBILE_ROOT[dest] ? dest : 'board', stack: [] }; }
+function mobPush(nav, screen) {
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  return { dest: n.dest, stack: n.stack.concat([mobScreen(Object.assign({ dest: n.dest }, screen))]) };
+}
+// Removes EXACTLY one. Back from a destination root is a no-op — it never exits the app and never
+// unwinds into another destination, which is the second half of P3.
+function mobPop(nav) {
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  return n.stack.length ? { dest: n.dest, stack: n.stack.slice(0, -1) } : { dest: n.dest, stack: [] };
+}
+// Choosing a destination RESETS it to its root with an empty stack — the prototype's {tab, stack:[]}.
+function mobSwitchDest(nav, dest) { return mobNavInit(dest); }
+function mobCurrentOf(nav) {
+  const n = nav && MOBILE_ROOT[nav.dest] ? nav : mobNavInit('board');
+  return n.stack.length ? n.stack[n.stack.length - 1] : mobRootOf(n.dest);
+}
+/* R11 — the legacy key is read ONCE, for migration, and never written again. Every value the old
+ * three-way switcher could hold, plus anything unrecognised and nothing at all, lands on `board`:
+ * the destination root is the only screen that is safe to draw without re-reading anything. */
+function mobMigrateView(v) { return MOBILE_ROOT[v] ? v : 'board'; }
+
+  return { push: mobPush, pop: mobPop, switchDest: mobSwitchDest, init: mobNavInit,
+    current: mobCurrentOf, titleOf: mobTitleOf, columnOf: mobColumnOf, panelOf: mobPanelOf,
+    destForMode: mobDestForMode,
+    MODE_TITLE,
+    migrateView: mobMigrateView, screen: mobScreen, root: mobRootOf,
+    DESTS: MOBILE_DESTS, DEST_FOR_MODE: MOBILE_DEST, ROOTS: MOBILE_ROOT,
+    PANEL_OF_KIND: MOBILE_PANEL, DETAIL_TITLE };
+});

package/workspace/lib/profiles.js

@@ -0,0 +1,285 @@
+'use strict';
+/*
+ * Claude profile descriptors — a PURE reader (initiative `workspace-profiles`, PRD R1/R2/R4/R6/R7).
+ *
+ * The workspace lets the PM name a profile when a session's process is created. This module is the
+ * half of that feature which decides WHAT IS TRUE: it reads `<home>/.claude/profiles/*.json` and
+ * reports what it found. It never spawns anything, never writes, and never touches the network.
+ *
+ * WHAT THIS MODULE IS NOT ALLOWED TO IMPLY. PMOS holds no credential, runs no MCP client, and
+ * cannot ask a running `claude` what configuration it is really using. So every value here is
+ * "what a file on this machine declares", never "what is true of the world". The naming below is
+ * deliberately clumsy in places (`declared`, `recorded`) because the shorter words all read as
+ * verified facts.
+ *
+ * HONESTY BY CONSTRUCTION — readProfiles() returns a FOUR-way discrimination, not a boolean.
+ * These are four different facts about the world and collapsing any pair of them produces a
+ * specific, known lie:
+ *
+ *   { ok:true,  absent:true,  profiles:[],    broken:[]   }  no ~/.claude/profiles directory.
+ *        A calm, stated absence. Nothing was read because there was nothing to read. The picker
+ *        renders the path and says so. It must NOT render `work`/`personal` chips: those are the
+ *        names the PM's machine is expected to carry, not names PMOS ships, and drawing them here
+ *        is the PRD's stated FAIL — a picker appears, a choice is made, and nothing was applied.
+ *
+ *   { ok:true,  absent:false, profiles:[],    broken:[]   }  the directory exists and is empty.
+ *        A SUCCESSFUL READ OF NOTHING. Same consequence for the PM, different fact: the directory
+ *        was created and left empty rather than never created. Calm, not red.
+ *
+ *   { ok:true,  absent:false, profiles:[…],   broken:[…]  }  some descriptors read, some did not.
+ *        R4: one bad file must not take the others down. The good ones are still offered; each bad
+ *        one is named with its filename and its reason so it renders RED. Note that `profiles` can
+ *        be EMPTY while `broken` is not — every descriptor on the machine is malformed. A consumer
+ *        that tests only `profiles.length` renders that as the calm empty state above, which
+ *        reports a failure as an emptiness. Check `broken.length` before drawing calm prose.
+ *
+ *   { ok:false, absent:false, profiles:[],    error:'…'   }  the directory could not be read.
+ *        Permissions, or a FILE sitting where the directory should be. This is the distinction the
+ *        module exists to protect: a missing directory and an unreadable one are different facts.
+ *        Defaulting an unreadable directory to "no profiles configured" would state a capability
+ *        claim the data does not support — it would tell the PM their machine has no profiles when
+ *        what actually happened is that PMOS could not look.
+ *
+ * `dir` is returned in every case, including the failures, because R2 and R10 both require the
+ * surface to NAME the path it read or failed to read. An absence with no path is an assertion the
+ * PM cannot check.
+ */
+const fs = require('fs');
+const path = require('path');
+
+// Where the agent CLI keeps them. PMOS does not define this format and never writes here (PRD
+// non-goal 3) — it is read-only to us, so an unexpected key is ignored rather than migrated.
+const PROFILE_SUBDIR = ['.claude', 'profiles'];
+
+function profilesDir(homeDir) { return path.join(homeDir, ...PROFILE_SUBDIR); }
+
+// Errors are shown to a human who has to go fix a file, so carry the code AND the message. Both
+// halves earn their place: the code says what kind of problem it is, the message says which path.
+// Node already prefixes most fs messages with the code, so only prepend it when it is missing —
+// "EISDIR: EISDIR: illegal operation" is noise in a line a PM is meant to act on.
+function describeErr(e) {
+  const msg = String((e && e.message) || e);
+  const code = e && e.code ? String(e.code) : '';
+  return (code && !msg.startsWith(code) ? `${code}: ${msg}` : msg).slice(0, 200);
+}
+
+const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const has = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+
+/*
+ * Validate one parsed descriptor against R1's table. Returns `{ profile }` or `{ error }`.
+ *
+ * The rule running through every branch: A KEY THAT IS PRESENT BUT WRONG-TYPED MAKES THE
+ * DESCRIPTOR UNREADABLE. It is never coerced and never dropped. The reason is that both softer
+ * options lie in the PM's favour. Coercing `mcp: "jira"` into `["jira"]` invents a declaration the
+ * file did not make; dropping it renders "no mcp servers declared in this profile" over a file
+ * that plainly declared one. Rejecting is loud, names the file, and leaves the other descriptors
+ * alone (R4) — the PM gets a fixable error instead of a quiet wrong answer.
+ *
+ * A key that is ABSENT is a different matter: R1 forbids substituting a default, so absence is
+ * carried through as `null` (account) or `[]` (mcp) for the consumer to state, not to fill in.
+ */
+function validate(raw, stem) {
+  if (!isPlainObject(raw)) {
+    const found = raw === null ? 'null' : Array.isArray(raw) ? 'an array' : typeof raw;
+    return { error: `is not a JSON object — found ${found}` };
+  }
+
+  // `id` is the identity the pane line, the session record and the descriptor path all cite, so it
+  // is the one key with no tolerated absence. Falling back to the filename stem would look
+  // harmless and be exactly the wrong thing: PMOS would be manufacturing the identity it then
+  // displays as read from the file, and a later rename would silently change which profile a
+  // session claims to have run under.
+  if (!has(raw, 'id')) {
+    return { error: 'declares no `id` — PMOS will not substitute the filename, because the id is the identity the pane and the session record cite' };
+  }
+  if (typeof raw.id !== 'string' || !raw.id) return { error: '`id` is present but is not a non-empty string' };
+  if (raw.id !== stem) {
+    return { error: `declares id "${raw.id}" but is filed as ${stem}.json — the descriptor's identity disagrees with its filename` };
+  }
+
+  let label = raw.id;                       // R1: display name, falls back to `id` when absent
+  if (has(raw, 'label')) {
+    if (typeof raw.label !== 'string' || !raw.label.trim()) return { error: '`label` is present but is not a non-empty string' };
+    label = raw.label;
+  }
+
+  // Displayed VERBATIM and always attributed to the file (R1). PMOS cannot verify an account
+  // string and does not try; if it is wrong on disk it is wrong on screen, which is why every
+  // surface that shows it also shows where it came from. Absent stays null — "not declared" is a
+  // thing the consumer can say, and is not the same as an empty account name.
+  let account = null;
+  if (has(raw, 'account')) {
+    if (typeof raw.account !== 'string') return { error: '`account` is present but is not a string' };
+    account = raw.account;
+  }
+
+  // R7: these are names a file declares, never servers PMOS reached. Absent and `[]` collapse to
+  // the same array on purpose — both mean "this descriptor declares no MCP servers", which is one
+  // fact with one honest phrasing. What must NOT collapse into it is a malformed `mcp`, above.
+  let mcp = [];
+  if (has(raw, 'mcp')) {
+    if (!Array.isArray(raw.mcp) || raw.mcp.some((x) => typeof x !== 'string')) {
+      return { error: '`mcp` is present but is not an array of server names' };
+    }
+    mcp = raw.mcp.slice();
+  }
+
+  // The only key with a mechanical effect: it becomes the environment overlay at process creation
+  // (R3). `null` (key absent) and `{}` (declared empty) are kept DISTINCT here even though both
+  // apply nothing, because the reader's job is to report the file faithfully; profileLine() is
+  // where they converge, and it converges them on the sentence that says nothing was applied.
+  let env = null;
+  if (has(raw, 'env')) {
+    if (!isPlainObject(raw.env)) return { error: '`env` is present but is not an object of environment variables' };
+    for (const k of Object.keys(raw.env)) {
+      if (typeof raw.env[k] !== 'string') {
+        return { error: `\`env.${k}\` is not a string — PMOS will not coerce a value into an environment variable it was not given` };
+      }
+    }
+    env = { ...raw.env };
+  }
+
+  return { profile: { id: raw.id, label, account, mcp, env } };
+}
+
+/*
+ * Read every descriptor under `<homeDir>/.claude/profiles`.
+ *
+ * `homeDir` is a parameter rather than `os.homedir()` read inside, which is what makes this
+ * testable against real fixture directories instead of against a mock of the filesystem. A caller
+ * with no home directory gets a stated failure; guessing one would be the same class of invention
+ * this whole module refuses.
+ */
+function readProfiles(homeDir) {
+  if (typeof homeDir !== 'string' || !homeDir) {
+    return {
+      ok: false, absent: false, dir: null, profiles: [], broken: [],
+      error: 'no home directory was given — PMOS will not guess where .claude/profiles lives',
+    };
+  }
+  const dir = profilesDir(homeDir);
+
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch (e) {
+    // THE DISTINCTION THIS MODULE EXISTS FOR. ENOENT is "there is nothing here", which is calm and
+    // true. Everything else — EACCES, ENOTDIR, EIO — is "PMOS could not look", which is a failure
+    // and must read red. Reporting the second as the first would tell the PM their machine has no
+    // profiles configured when PMOS never got far enough to know.
+    if (e && e.code === 'ENOENT') return { ok: true, absent: true, dir, profiles: [], broken: [], error: null };
+    if (e && e.code === 'ENOTDIR') {
+      return { ok: false, absent: false, dir, profiles: [], broken: [], error: `${dir} is not a directory — a file is sitting where the profiles directory should be` };
+    }
+    return { ok: false, absent: false, dir, profiles: [], broken: [], error: `${dir} could not be read — ${describeErr(e)}` };
+  }
+
+  const profiles = [];
+  const broken = [];
+  // Sorted so the picker's chip order is stable across reads. Directory order is not.
+  for (const name of names.slice().sort()) {
+    if (!name.endsWith('.json')) continue;     // not a descriptor at all — not a failed one either
+    const file = path.join(dir, name);
+    const stem = name.slice(0, -'.json'.length);
+
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf8');
+    } catch (e) {
+      // Includes EISDIR: a DIRECTORY named `something.json`. Reported rather than skipped — it
+      // occupies the name a descriptor would have, so silently passing over it would leave the PM
+      // looking at a picker missing a chip with nothing anywhere saying why.
+      broken.push({ file: name, path: file, error: `could not be read — ${describeErr(e)}` });
+      continue;
+    }
+
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch (e) {
+      broken.push({ file: name, path: file, error: `is not valid JSON — ${String((e && e.message) || e).slice(0, 140)}` });
+      continue;
+    }
+
+    const v = validate(raw, stem);
+    if (v.error) { broken.push({ file: name, path: file, error: v.error }); continue; }
+    profiles.push({ ...v.profile, path: file });
+  }
+
+  // ok:true means THE DIRECTORY was read. It does not mean every file in it was. R4 requires those
+  // to be separable, so a malformed descriptor lands in `broken` and leaves its neighbours usable.
+  return { ok: true, absent: false, dir, profiles, broken, error: null };
+}
+
+/*
+ * The one line naming what a pane is running under — PRD R6, verbatim sentences.
+ *
+ * DIVERGENCE FROM THE DESIGN, recorded rather than glossed. `HANDOFF.md` §3 asks for
+ * `profile: claude-work · mcp: jira confluence slack gworkspace`, and `mcp: none` for the other
+ * case. This returns the PRD's R6/R7 wording instead, for two reasons the PRD states and the
+ * design does not address:
+ *   - `mcp: none` reads as a checked fact about the world. PMOS has no MCP client and never
+ *     contacted anything; the only thing it knows is what the descriptor declared. R7 forbids the
+ *     phrase outright, and the honest replacement is "no mcp servers declared in this profile".
+ *   - the design's line has no way to say "the profile declares no environment overlay", which is
+ *     the case where the PM is most likely to believe a choice took effect when nothing did.
+ * If the literal design string is wanted it is a PM ruling, not an implementation detail.
+ *
+ * "applied N environment variables" IS A CLAIM ABOUT THE SPAWN, not about the file. This function
+ * is a formatter and cannot verify it. The caller must therefore only pass a descriptor for a
+ * session PMOS actually created with that descriptor's overlay (R3); rendering this line from a
+ * descriptor that was merely selected would state an application that never happened.
+ *
+ * The three no-descriptor cases are distinguished by the ARGUMENT'S OWN TYPE, because they survive
+ * a JSON round-trip differently and a session record is JSON:
+ *   undefined / key absent → "not recorded"     (an orphan tmux pane, or a record persisted before
+ *                                                this feature existed — inventing a profile for it
+ *                                                would be a lie about the past)
+ *   null                   → "none was chosen"  (PMOS started it and recorded that nothing was
+ *                                                picked; `null` is written explicitly so it does
+ *                                                not decay into the case above)
+ * A bare id STRING is rejected on purpose: what was applied is a fact about the descriptor, so a
+ * caller holding only an id must resolve it through readProfiles() first (R9 — a respawn whose
+ * descriptor has since been deleted must not substitute another).
+ */
+function profileLine(profile, read) {
+  if (profile === undefined) return 'profile: not recorded — PMOS did not start this pane';
+
+  if (profile === null) {
+    // Only claim the machine has none configured when the read in hand actually says so. A read
+    // that failed, or one that found broken descriptors, does not support that sentence — the
+    // profiles may well be there and unreadable.
+    const noneConfigured = !!read && read.ok === true &&
+      (read.absent === true ||
+        ((read.profiles || []).length === 0 && (read.broken || []).length === 0));
+    return noneConfigured
+      ? 'no profile — none was chosen (no profiles are configured on this machine)'
+      : 'no profile — none was chosen for this session';
+  }
+
+  if (!isPlainObject(profile)) return 'profile: unreadable — the recorded value is not a profile descriptor';
+
+  // `label` is the declared display name (R1) but `id` is the traceable one: it is the descriptor's
+  // filename stem, so a reader can go check the file. Label wins where present because the spec
+  // says so; where it is absent the id carries the line.
+  const name = (typeof profile.label === 'string' && profile.label) ? profile.label
+    : (typeof profile.id === 'string' && profile.id) ? profile.id : null;
+  if (!name) return 'profile: unreadable — the recorded descriptor names no profile';
+
+  const n = isPlainObject(profile.env) ? Object.keys(profile.env).length : 0;
+  if (n === 0) {
+    // Covers both "no `env` key" and "`env: {}`". They differ on disk and are identical to the PM:
+    // nothing was applied. Saying "applied 0 environment variables" would be the precise phrasing
+    // most likely to be read as success, so R6 replaces it with a sentence about consequence.
+    return `profile: ${name} — the profile declares no environment overlay; this session runs with the workspace's default environment`;
+  }
+
+  const vars = `applied ${n} environment variable${n === 1 ? '' : 's'}`;
+  const mcp = (Array.isArray(profile.mcp) && profile.mcp.length)
+    ? `mcp declared by the profile: ${profile.mcp.join(' ')}`
+    : 'no mcp servers declared in this profile';
+  return `profile: ${name} — ${vars} · ${mcp}`;
+}
+
+module.exports = { readProfiles, profileLine, profilesDir, PROFILE_SUBDIR };