create-pmos 0.14.0 → 0.16.0

package/workspace/server.js

@@ -25,7 +25,7 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
-const { execFile, spawnSync } = require('child_process');
+const { execFile, spawnSync, spawn } = require('child_process');
 const { WebSocketServer } = require('ws');
 
 // node-pty is a NATIVE module; a broken/mismatched build is the #1 field failure
@@ -75,6 +75,15 @@ const tmuxControl = require('./lib/tmux-control');     // tmux -CC protocol: the
 const relatedDocs = require('./lib/related-docs');            // which documents a change puts out of step (R5/R6)
 const applyChange = require('./lib/apply-change');            // anchored + whole-document saves, refuse-on-stale
 const sessionState = require('./lib/session-state');   // the cadence×turn join — validated on BOTH sides
+// Bundle 2 (planning/design/bundle-2-wiring-contract.md). Four already-built pure modules. The
+// server's whole job for these four features is to READ the filesystem and hand the result over —
+// none of their logic is re-derived here, because a second implementation of "what does this
+// record declare" is how two surfaces come to disagree about the same file.
+const repoScan = require('./lib/repo-scan');           // scanRepo(root) — pure, cannot write (ingest R3)
+const profilesLib = require('./lib/profiles');         // readProfiles(homeDir) / profileLine(profile, read)
+const focus = require('./lib/focus');                  // buildFocus(input) → FocusView (cross-product)
+const handoff = require('./lib/handoff');              // readLinks(parsedFrontmatterObject) — never a path
+const fourPanel = require('./lib/four-panel');         // GET /api/initiative — the one-initiative join + the declaration stores
 // The "home" repo this server manages. In PMOS-self the app ships INSIDE its repo
 // (pmos/workspace) so the parent dir IS the repo. But a kit/tenant copy is installed standalone
 // — `npm i -g` puts it under node_modules/pmos-workspace, or it runs from an npx bundle — and
@@ -98,12 +107,20 @@ const EMBEDDED_SELF = !INSTALLED_COPY && SELF_ROOT === PARENT_DIR &&
 // (unsupported direct run) has no home — the client must open a repo to do anything.
 const HOME_ENABLED = EMBEDDED_SELF || (!!process.env.PMOS_SELF_ROOT && dirExists(SELF_ROOT));
 const PUB = path.join(__dirname, 'public');
+const PM_DIR = path.join(PUB, 'pm');   // the four-panel front end — served as a directory, guarded below
 const XROOT = path.join(__dirname, 'node_modules', '@xterm');
 const STATE = path.join(__dirname, 'state');
 const SESS_DIR = path.join(STATE, 'sessions');
 const SCRATCH_DIR = path.join(STATE, 'scratchpad');   // per-workspace staging text (D62; local-only, gitignored)
 const LAYOUT_DIR = path.join(STATE, 'layouts');       // per-workspace arrangements (R7; local-only, gitignored)
 const WS_FILE = path.join(STATE, 'workspaces.json');
+// Ingest proposals live BESIDE workspaces.json, never inside the repo being scanned (ingest R3):
+// a proposal that is never accepted must leave the clone byte-identical.
+const INGEST_DIR = path.join(STATE, 'ingest');
+const CLONE_DIR = path.join(STATE, 'clones');
+// PMOS's OWN memory of which profile to preselect per agent binary (profiles R8.2). It is a
+// workspace preference, not an agent attribute — the file lives here for exactly that reason.
+const PREFS_FILE = path.join(STATE, 'prefs.json');
 const PORT = process.env.PMOS_WS_PORT ? Number(process.env.PMOS_WS_PORT) : 7433;
 const preview = require('./lib/preview-kind');         // the single reader classifier (md|text|html|image|inert)
 const layoutModel = require('./lib/layout');           // the arrangement model — validated on BOTH sides
@@ -139,6 +156,67 @@ function sessionEnv() {
   for (const k of Object.keys(env)) if (/^CLAUDE_CODE_/.test(k)) delete env[k];
   return env;
 }
+
+// ── Agent profiles (workspace-profiles). ──────────────────────────────────────────────────────
+// A profile is a DESCRIPTOR the PM already keeps at ~/.claude/profiles/*.json. PMOS reads it and
+// applies its `env` overlay when it creates a process — that is the whole mechanism. It runs no
+// MCP client, checks no reachability and holds no credential, so nothing here may say "connected".
+//
+// The read is not cached. A descriptor added while the workspace is open must appear on the next
+// look, and a stale copy of a file whose whole purpose is provenance is worse than a re-read.
+function readProfilesNow() { return profilesLib.readProfiles(os.homedir()); }
+/** One descriptor by id, or null. Returns the READ too, because profileLine(null, read) needs it
+ *  to tell "no profiles on this machine" from "the read failed and we cannot say". */
+function profileById(id) {
+  const read = readProfilesNow();
+  if (id == null || id === '') return { read, profile: null };
+  const profile = (read.profiles || []).find((p) => p.id === id) || null;
+  return { read, profile };
+}
+// `env` VALUES NEVER CROSS THE WIRE (contract §1.3). An environment overlay is exactly where a
+// credential lives, and D08's never-log-headers discipline covers anything the browser receives.
+// The names are shipped so the pane can say WHAT was applied; the values are not.
+function profileWire(p, read) {
+  const env = p && p.env && typeof p.env === 'object' ? p.env : {};
+  const keys = Object.keys(env);
+  return {
+    id: p.id, label: p.label == null ? null : p.label, account: p.account == null ? null : p.account,
+    mcp: Array.isArray(p.mcp) ? p.mcp.slice() : [],
+    env_count: keys.length, env_keys: keys,
+    // Computed HERE, once, so no surface can re-word R6's five sentences.
+    line: profilesLib.profileLine(p, read),
+  };
+}
+// PMOS's own memory: agent binary name → preferred profile id. It preselects the composer and
+// starts nothing (R8.2). Read fresh; a corrupt file is treated as no memory rather than crashing
+// a spawn — the preference is a convenience, and losing it costs one click.
+function readPrefs() {
+  try { const o = JSON.parse(fs.readFileSync(PREFS_FILE, 'utf8')); return o && typeof o === 'object' && !Array.isArray(o) ? o : {}; }
+  catch { return {}; }
+}
+function writePrefs(prefs) {
+  try { fs.writeFileSync(PREFS_FILE, JSON.stringify(prefs)); return null; }
+  catch (e) { warnWriteFail('prefs.json (profile preselection)', e); return `the preference could not be saved — ${String((e && e.code) || 'write failed')}`; }
+}
+// The merged environment a session actually runs under. The overlay goes ON TOP of sessionEnv(),
+// AFTER the marker-stripping (R3) — never instead of it, or a profile would silently re-enable the
+// nested-session markers sessionEnv exists to remove.
+function sessionEnvWithProfile(profile) {
+  const env = sessionEnv();
+  for (const [k, v] of Object.entries(profileOverlay(profile))) env[k] = v;
+  return env;
+}
+// Just the DELTA a profile introduces, stringified — never merged with the base. The tmux path
+// needs these separately from sessionEnv() because a pane's environment does not come from the
+// process that ran `new-session`: see createTmuxSession.
+function profileOverlay(profile) {
+  const out = {};
+  if (profile && profile.env && typeof profile.env === 'object') {
+    for (const k of Object.keys(profile.env)) out[k] = String(profile.env[k]);
+  }
+  return out;
+}
+
 const SCROLLBACK = 200_000;                            // bytes of ring buffer per session
 // How often the server re-broadcasts the session list while anything is alive (see heartbeat()).
 // 2s is chosen against what it drives: the state dot and the quiet clock. QUIET_AFTER_MS is 30s, so
@@ -230,10 +308,15 @@ function repoIdentity(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, branchCode = null;
+  let remote = null;
   try {
     const trees = gitInfo.worktrees(root);
     if (trees.length && trees[0].dir) { key = path.resolve(trees[0].dir); name = path.basename(key); }
   } catch { /* not a repo, or git absent — the tree is its own group, which is the truth */ }
+  // Where this tree came FROM. Memoised with the rest of the identity (same 15s TTL) because it is
+  // another `git` shell-out on a call that runs for every workspace on every push. A failure is not
+  // a fault: a folder registered by path legitimately has no origin, and null is the honest answer.
+  try { remote = gitInfo.originUrl(root); } catch { remote = null; }
   try {
     const bi = gitInfo.branchInfo(root);
     if (bi.ok) branch = bi.detached ? null : bi.current;
@@ -246,7 +329,7 @@ function repoIdentity(root) {
     // 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 };
+  const val = { at: now, key, name, branch, branchError, branchCode, remote };
   repoKeyCache.set(root, val);
   return val;
 }
@@ -262,6 +345,14 @@ function wsList() {
       // the client renders the first quietly and the second as a fault (R1/R2).
       repo_key: rid.key, repo_name: rid.name, branch: rid.branch,
       branch_error: rid.branchError, branch_code: rid.branchCode,
+      // Where the tree came from, and the ONE label the repository list can honestly put on a row.
+      // `remote` is the raw origin URL (null when there is none) so a caller can derive a richer
+      // answer without guessing; `kind` is the surface's own two-value vocabulary — a repository
+      // cloned from GitHub, or a folder on this machine. A remote that is not GitHub's reads as
+      // `local`, because `github` would be a claim about a host nobody contacted. Deriving `github`
+      // from the mere presence of a `.git` directory is what this replaces.
+      remote: rid.remote,
+      kind: gitInfo.isGithubRemote(rid.remote) ? 'github' : 'local',
     };
   });
 }
@@ -669,9 +760,34 @@ function surfaceRoadmap(root, w) {
 // (KR\d+) — so `## O-INTEGRITY` and `KR-C` were invisible here while the ladder happily accepted
 // anchors naming them. One field with two opinions is the defect this initiative removes; a second
 // parser would have been the same bug wearing a different regex.
+/* WHERE THE RESOLVER ACTUALLY LIVES — the same two-location lookup `lib/console-state.js` already
+ * does for the workflow engine, and for the same reason (incident kit-workflow-engine-missing).
+ * This function looked ONLY at `../scripts/anchor-resolve.js`, which exists in a PMOS checkout and
+ * nowhere else: the published package ships bin/ payload/ workspace/, so in an adopter's install
+ * there is no `scripts/` beside the app and every OKR and spine read answered "the anchor resolver
+ * is not present in this install". Panel 1 showed no count and panel 2 no groups, in every release
+ * that had the surface.
+ *
+ * It was invisible to every existing check because a dev checkout always has the file one directory
+ * up — the identical blind spot that hid the engine. It was found by launching the INSTALLED app
+ * with egress blocked (.github/scripts/offline-workspace-smoke.js), which is the shape adopters get
+ * and the shape nothing used to run.
+ *
+ *   1. `../scripts/anchor-resolve.js` — a repo checkout, preferred so a dev panel and CI cannot
+ *      disagree about what resolves.
+ *   2. `lib/engine/anchor-resolve.js` — the copy `scripts/vendor-workspace-engine.js` vendors into
+ *      the bundle (it is in the engine's own require closure, so it is already shipped). This is
+ *      what an adopter runs. */
+const ANCHOR_LIB_PATHS = [
+  path.join(__dirname, '..', 'scripts', 'anchor-resolve.js'),
+  path.join(__dirname, 'lib', 'engine', 'anchor-resolve.js'),
+];
 function anchorLib() {
-  try { return require(path.join(__dirname, '..', 'scripts', 'anchor-resolve.js')); }
-  catch { return null; }
+  for (const p of ANCHOR_LIB_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try { return require(p); } catch { return null; }
+  }
+  return null;
 }
 function surfaceOkr(root) {
   const A = anchorLib();
@@ -717,6 +833,97 @@ function surfaceOkr(root) {
     note: 'KR current/target and the lever tree are net-new state — shown as "— not tracked"',
   };
 }
+// ── The PM spine (workspace-pm-spine): Objective → Key Result → Initiative. ────────────────────
+// surfaceOkr() above reads the SAME objectives and KRs and deliberately stops short — its comment
+// calls the initiative↔KR join "an explicit non-goal". That left the workspace able to say an
+// anchor is VALID while unable to say what a KR is MADE OF, and left the UI rooted on the delivery
+// substrate (repo → tree → session) with the initiative reduced to a string parsed out of a branch
+// name. This function is that join, and nothing more: it re-uses anchor-resolve.js rather than
+// re-parsing anything, so there is exactly one definition of what an anchor means (R1).
+//
+// It deliberately returns NO runtime state. Which working trees and sessions are on an initiative
+// is a client-side attachment (the client already holds both, live over the socket) — keeping the
+// server's answer purely the PM structure means a spine that is correct whether or not anything is
+// currently checked out, which is the case R2 exists to make possible.
+function surfaceSpine(root) {
+  const A = anchorLib();
+  if (!A) {
+    return { objectives: [], budgets: [], unanchored: [], unreadable: 'the anchor resolver (scripts/anchor-resolve.js) is not present in this install — the spine cannot be derived here' };
+  }
+  const index = A.parseOkrIndex(root);
+  // R5 — a read that FAILED is not a read that found nothing. Unreadable renders RED; the calm
+  // empty state is reserved for a successful read of genuinely nothing.
+  if (!index.ok) {
+    return { objectives: [], budgets: [], unanchored: [], unreadable: index.error || 'the OKR documents could not be read' };
+  }
+  const budgetsDoc = A.readBudgets(root);
+
+  // the empty spine, keyed for O(1) attachment below
+  const objectives = index.objectives.map((o) => ({
+    id: o.token, key: o.id, name: (o.name || '').slice(0, 140), file: o.file,
+    krs: o.krs.map((k) => ({ id: k.token, key: k.id, name: (k.name || '').slice(0, 160), initiatives: [] })),
+  }));
+  const krByKey = new Map();
+  for (const o of objectives) for (const k of o.krs) krByKey.set(`${o.key}::${k.key}`, k);
+  const objByKey = new Map(objectives.map((o) => [o.key, o]));
+
+  const budgets = new Map();       // health:<id> groups — peers of objectives (D59), not a footnote
+  const unanchored = [];           // R6 — never dropped to make the tree tidy
+
+  for (const dir of findDirsNamed(root, 'initiatives', BUNDLE_MAX_DEPTH)) {
+    let files = [];
+    try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort(); } catch { continue; }
+    for (const f of files) {
+      if (f === 'README.md' || f === 'index.md') continue;
+      const fm = leadingFrontmatter(path.join(dir, f)) || {};
+      const id = String(fm.id || f.replace(/\.md$/, ''));
+      const rec = {
+        id,
+        title: String(fm.title || '').slice(0, 160),
+        lane: String(fm.lane || 'feature'),
+        file: path.relative(root, path.join(dir, f)),
+        // R7 — position is DERIVED by the workflow engine. No `stage:`/`status:` is read for it;
+        // `status` is carried only because the chore lane's intent lives there as prose.
+        has_spec: !!String(fm.prd_path || '').trim(),
+        has_rubric: !!String(fm.rubric_path || '').trim(),
+      };
+      const raw = fm.parent_kr == null ? '' : String(fm.parent_kr);
+      const r = A.resolveAnchor(raw, index, budgetsDoc);
+
+      if (r.kind === 'health' && r.status === 'resolved') {
+        const key = `health:${r.budget}`;
+        if (!budgets.has(key)) budgets.set(key, { id: key, name: r.budget, initiatives: [] });
+        budgets.get(key).initiatives.push(rec);
+        continue;
+      }
+      if (r.kind === 'okr' && r.status === 'resolved') {
+        const kr = r.kr ? krByKey.get(`${A.objectiveId(r.objective)}::${A.krId(r.kr)}`) : null;
+        if (kr) { kr.initiatives.push(rec); continue; }
+        // resolved to an OBJECTIVE with no KR named — real and legitimate, but it has no KR bucket
+        const obj = objByKey.get(A.objectiveId(r.objective));
+        if (obj) {
+          if (!obj.direct) obj.direct = [];
+          obj.direct.push(rec);
+          continue;
+        }
+      }
+      // R6 — anything that did not resolve is LISTED, with the resolver's own reason. This is the
+      // set surfaceOkr() only ever counted.
+      unanchored.push(Object.assign({}, rec, {
+        raw: raw.trim().slice(0, 100),
+        status: r.status,
+        reason: r.reason || 'this anchor does not resolve against the OKR documents or the health-budget registry',
+      }));
+    }
+  }
+  return {
+    objectives,
+    budgets: [...budgets.values()].sort((a, b) => a.id.localeCompare(b.id)),
+    unanchored,
+    unreadable: null,
+    budgets_readable: !!(budgetsDoc && budgetsDoc.ok),
+  };
+}
 function surfaceReport(root, w) {
   const s = surfaceInitiatives(root, w);
   const line = (i) => `${i.id}${i.title ? ' — ' + i.title : ''}`;
@@ -798,12 +1005,19 @@ function fireSchedule(sched) {
   // AGENT task — fire as a real PTY session running its skill (async; the skill files its own
   // deliverable). The workspace starts it + stamps 'started'; run-now and the tick share this path.
   if (task && task.kind === 'agent') {
+    // The schedule's recorded profile travels with the process it creates (profiles R8.3). Only an
+    // AGENT-kind task has a PTY, which is why `profile_applies` is false for the skill-kind rows
+    // below rather than the control simply being hidden.
     const s = spawnSession({ name: sched.name, agent: task.agent || 'claude', ws: sched.ws,
-      origin: 'schedule:' + sched.id, initialInput: task.prompt ? task.prompt + '\r' : null });
+      origin: 'schedule:' + sched.id, initialInput: task.prompt ? task.prompt + '\r' : null,
+      profile: sched.profile == null ? null : sched.profile });
     const list = readSchedules(); const cur = list.find((x) => x.id === sched.id);
     const started = s.state !== 'exited';
     if (cur) { cur.lastRun = nowISO(); cur.lastStatus = started ? 'started' : 'fail'; cur.nextRun = scheduleLogic.nextRun(cur); writeSchedules(list); }
-    return { ok: started, kind: 'agent', sessionId: s.id, reason: started ? '' : (s.note || 'could not start the session') };
+    // A run that started WITHOUT the profile it recorded is reported as such rather than as a
+    // clean start: the session is real, the environment is not the one the schedule declared.
+    return { ok: started, kind: 'agent', sessionId: s.id,
+      reason: started ? (s.profileRefusal || '') : (s.note || 'could not start the session') };
   }
   const runId = `sched-${sched.id}-${Date.now()}`;
   let ok = false, deliverable = null, reason = '';
@@ -855,6 +1069,11 @@ function persist(s) {
   // so a session survives even if the workspace registry is lost (it re-registers its root).
   const meta = { id: s.id, ws: s.ws, root: s.root, name: s.name, agent: s.agent, cwd: s.cwd,
     state: s.state, note: s.note || '', created: s.created, tmux: s.tmux || null, origin: s.origin || null };
+  // The profile ID ONLY — never the descriptor and never its env, which is where a credential
+  // would live (D08). The key is written only for a session PMOS created, so its ABSENCE stays a
+  // fact: a record persisted before profiles existed restores as "not recorded", and inventing a
+  // key for the past would be a lie about it.
+  if ('profile' in s) meta.profile = s.profile == null ? null : s.profile;
   try {
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.json'), JSON.stringify(meta));
     fs.writeFileSync(path.join(SESS_DIR, s.id + '.scrollback'), s.buf);
@@ -866,7 +1085,7 @@ function unpersist(id) {
   }
 }
 // Scrollback written by the PRE-control-mode architecture carries the tmux CLIENT's own screen
-// setup, and that gets replayed verbatim into a fresh xterm.js on attach (public/app.js) — putting
+// setup, and that gets replayed verbatim into a fresh xterm.js on attach (public/pm/tab-term.js) — putting
 // the terminal straight back into the alternate buffer, where there is no scrollback. Strip it.
 //
 // The two signatures below are the client's, not an application's: the alt-screen switch IMMEDIATELY
@@ -1078,6 +1297,12 @@ function harnessOf(s) {
 }
 function sessionList() {
   const now = Date.now();
+  // ONE profiles read per broadcast, not one per session: the line is a formatter over the
+  // descriptor, and re-reading the directory per row would turn a 2s heartbeat into a directory
+  // scan per pane. A read that FAILED is passed through as-is — profileLine() needs to see the
+  // failure to avoid claiming "no profiles are configured on this machine" when PMOS never looked.
+  const pread = readProfilesNow();
+  const byId = new Map((pread.profiles || []).map((p) => [p.id, p]));
   return [...sessions.values()].map((s) => {
     const d = harness.deriveState(s.state, s.lastOutputAt, now);
     const h = harnessOf(s);
@@ -1098,6 +1323,24 @@ function sessionList() {
       // double the transcript work the TX_REREAD_MS floor exists to bound.
       hx,
       missing: h.missing,
+      // ── profiles (workspace-profiles R6). Two fields, and the second is a SENTENCE. ──
+      // `profile_line` is always a string, computed here rather than on the client, because the
+      // three no-descriptor cases are distinguished by the ARGUMENT'S OWN TYPE and `undefined`
+      // cannot survive JSON.stringify: a session PMOS never started (no `profile` key at all →
+      // "not recorded") and one PMOS started with nothing picked (`null` → "none was chosen") would
+      // arrive on the wire identical. Computing the sentence server-side is what preserves them.
+      // A recorded id whose descriptor has since been deleted resolves to no descriptor, and the
+      // line says so rather than substituting another profile (R9).
+      // A recorded id whose descriptor has since been deleted is handed to profileLine() AS THE
+      // BARE ID — the module rejects a bare string on purpose ("the recorded value is not a
+      // profile descriptor"), which is the honest answer. Resolving it to `null` instead would
+      // print "none was chosen" over a session that did choose one (R9).
+      profile_id: 'profile' in s ? (s.profile == null ? null : s.profile) : null,
+      profile_line: profilesLib.profileLine(
+        !('profile' in s) ? undefined
+          : s.profile == null ? null
+            : (byId.get(s.profile) || s.profile),
+        pread),
     };
   });
 }
@@ -1241,7 +1484,10 @@ function writeTmuxConf() {
 }
 // A tmux CONTROL command (not the attach PTY). Uses the CLEANED session env so that the cold
 // start this may trigger seeds the tmux server's own environment marker-free (D62 / sessionEnv).
-function tmuxCtl(args) { return spawnSync(TMUX, ['-L', TMUX_SOCK, ...args], { env: sessionEnv(), encoding: 'utf8' }); }
+// `env` is an OPT-IN override and only `new-session` ever passes one (profiles R3). has-session /
+// kill-session / list-sessions / display-message have no session context, so handing them a
+// profile's overlay would apply it to whichever pane the command happened to touch — a silent bug.
+function tmuxCtl(args, env) { return spawnSync(TMUX, ['-L', TMUX_SOCK, ...args], { env: env || sessionEnv(), encoding: 'utf8' }); }
 function tmuxHasSession(name) { return !!TMUX && tmuxCtl(['has-session', '-t', name]).status === 0; }
 function tmuxKillSession(name) { if (TMUX && name) tmuxCtl(['kill-session', '-t', name]); }
 // Create the tmux session a FRESH spawn runs in. It REFUSES a name that already exists rather
@@ -1249,10 +1495,25 @@ function tmuxKillSession(name) { if (TMUX && name) tmuxCtl(['kill-session', '-t'
 // name is someone else's process, in someone else's directory. Silently reusing it is how a new
 // session came up in the wrong repo. freshTmuxName makes the collision practically impossible;
 // this is the floor that keeps it impossible even if it were not.
-function createTmuxSession(name, cmd, workdir, cols, rows) {
+//
+// THE PROFILE OVERLAY TRAVELS AS `-e`, NEVER AS THIS PROCESS'S ENV. A pane does not inherit the
+// environment of the process that ran `new-session` — it inherits the tmux SERVER's, which was
+// fixed at whatever cold-started the daemon. Handing the overlay to the client therefore did two
+// wrong things at once, both measured on tmux 3.4 before this line changed:
+//   · the FIRST profiled session cold-started the server and seeded ITS overlay into the daemon,
+//     so every later pane on the socket inherited it — a `personal` session and a session with no
+//     profile at all both came up carrying the `work` overlay;
+//   · while the pane's own profile line went on naming the profile that session had asked for.
+// A workspace that runs a personal session under work credentials and then TELLS the PM it did
+// not is the honest-state contract inverted, so this is a correctness fix and not a tidy-up.
+// `new-session -e K=V` (tmux ≥3.2) sets the environment of THAT session only; a session that
+// declares no profile is left genuinely unset rather than inheriting a neighbour's.
+function createTmuxSession(name, cmd, workdir, cols, rows, overlay) {
   if (tmuxHasSession(name)) return false;
+  const eArgs = [];
+  for (const [k, v] of Object.entries(overlay || {})) eArgs.push('-e', `${k}=${v}`);
   const r = tmuxCtl(['-f', TMUX_CONF, 'new-session', '-d', '-s', name,
-    '-x', String(cols || 80), '-y', String(rows || 24), '-c', workdir, '--', cmd]);
+    ...eArgs, '-x', String(cols || 80), '-y', String(rows || 24), '-c', workdir, '--', cmd]);
   return r.status === 0;
 }
 // Every session alive on our private socket, with the directory its pane is actually sitting in.
@@ -1396,8 +1657,8 @@ function attachPty(s, { seed = false } = {}) {
 }
 
 // Try a command, falling back to `sh` on posix if the preferred shell can't spawn.
-function spawnPty(cmd, workdir) {
-  const opts = { name: 'xterm-256color', cols: 80, rows: 24, cwd: workdir, env: sessionEnv() };
+function spawnPty(cmd, workdir, env) {
+  const opts = { name: 'xterm-256color', cols: 80, rows: 24, cwd: workdir, env: env || sessionEnv() };
   const chain = process.platform === 'win32' ? [cmd] : [...new Set([cmd, 'sh', '/bin/sh'])];
   let lastErr;
   for (const c of chain) {
@@ -1432,7 +1693,24 @@ function nextSessionId() {
   return id;
 }
 
-function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
+// Resolve a requested profile id BEFORE anything is spawned (profiles R3/R9). The rule the whole
+// feature turns on: a session must never claim a profile whose overlay was not applied. So the
+// three outcomes are kept apart — nothing asked for, asked for and readable, asked for and gone —
+// and callers that can refuse (the composer) refuse rather than start something mislabelled.
+function resolveProfileForSpawn(id) {
+  if (id == null || id === '') return { ok: true, id: null, profile: null };
+  const { read, profile } = profileById(String(id));
+  if (profile) return { ok: true, id: profile.id, profile };
+  if (!read.ok) return { ok: false, id: null, profile: null, error: `profile "${id}" could not be checked — ${read.error}` };
+  const bad = (read.broken || []).find((b) => b.file === `${id}.json`);
+  if (bad) return { ok: false, id: null, profile: null, error: `profile "${id}" is not usable — ${bad.file} ${bad.error}` };
+  return { ok: false, id: null, profile: null,
+    error: read.absent
+      ? `profile "${id}" was asked for, but ${read.dir} does not exist — no descriptor was read and nothing would be applied`
+      : `profile "${id}" is not among the descriptors in ${read.dir} — PMOS will not substitute another` };
+}
+
+function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile }) {
   const id = nextSessionId();
   const w = getWs(ws);
   const root = w ? w.root : SELF_ROOT;
@@ -1445,7 +1723,14 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
   const cmd = isShell ? (commandExists(SHELL) ? SHELL : 'sh') : agent;
   // a session's working directory is confined to its OWN workspace root (R3)
   const workdir = cwd && insideRoot(root, path.resolve(root, cwd)) ? path.resolve(root, cwd) : root;
-  const base = { id, ws: w ? w.id : wsId(SELF_ROOT), root, name: (name && String(name).trim()) || agent, agent, origin: tag };
+  // Resolved once, here, so every path below spawns under the SAME environment the record claims.
+  // `pres.id` is null whenever the overlay was not applied — including when a profile was asked for
+  // and could not be read — so the pane line can never name a profile that did nothing (R3/R9).
+  // `profileRefusal` is server-internal: callers that can refuse read it and say why.
+  const pres = resolveProfileForSpawn(profile);
+  const penv = sessionEnvWithProfile(pres.profile);
+  const base = { id, ws: w ? w.id : wsId(SELF_ROOT), root, name: (name && String(name).trim()) || agent, agent, origin: tag,
+    profile: pres.id, profileRefusal: pres.ok ? null : pres.error };
 
   // A missing agent CLI is detected BEFORE any spawn (on Linux the exec-in-fork failure is
   // otherwise silent) — the same honest exited pane on both the tmux and the direct path.
@@ -1460,7 +1745,9 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
     const s = { ...base, cwd: workdir, state: 'working', pty: null, tmux: tname,
       note: '', buf: '', cols: 80, rows: 24, clients: new Set(), created: nowISO() };
     sessions.set(id, s);
-    if (!createTmuxSession(tname, cmd, workdir, 80, 24)) {
+    // the OVERLAY, not the merged env — the merged env is for the direct-PTY path below, which
+    // really does spawn the process itself. See createTmuxSession for why the two differ.
+    if (!createTmuxSession(tname, cmd, workdir, 80, 24, profileOverlay(pres.profile))) {
       const why = `could not start a tmux session for '${cmd}'. Run \`npm run doctor\` in workspace/.`;
       s.state = 'exited'; s.tmux = null; s.note = why;
       s.buf = `\x1b[38;5;203m✗ ${why}\x1b[0m\r\n\x1b[38;5;244mFix the above, then ↻ respawn.\x1b[0m\r\n`;
@@ -1475,8 +1762,8 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
   const startedMs = Date.now();
   let p, usedCmd = cmd;
   try {
-    if (isShell) { const r = spawnPty(cmd, workdir); p = r.pty; usedCmd = r.cmd; }
-    else p = pty.spawn(cmd, [], { name: 'xterm-256color', cols: 80, rows: 24, cwd: workdir, env: sessionEnv() });
+    if (isShell) { const r = spawnPty(cmd, workdir, penv); p = r.pty; usedCmd = r.cmd; }
+    else p = pty.spawn(cmd, [], { name: 'xterm-256color', cols: 80, rows: 24, cwd: workdir, env: penv });
   } catch (e) {
     return exitedSession(base, workdir, spawnFailureAdvice(e, cmd, isShell));
   }
@@ -1518,9 +1805,14 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput }) {
 // A FAILED git operation in a real repo must never spawn a session on the wrong branch (rubric
 // hard floor): we return {ok:false} and spawn nothing. Kept as its own function so the
 // git-then-maybe-spawn contract is unit-testable without a WS client.
-function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate }) {
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile }) {
   const w = getWs(ws);
   if (!w) return { ok: false, error: 'no workspace' };
+  // The profile is checked BEFORE any git operation. A composer that picked a profile PMOS cannot
+  // read must not leave a branch checked out and a session running under the wrong environment —
+  // and a session that claims a profile it never got is the quietest failure this feature has.
+  const pres = resolveProfileForSpawn(profile);
+  if (!pres.ok) return { ok: false, error: pres.error };
   let targetWs = w.id;
   let notice = null;
   // Isolation exists to protect OTHER sessions. Alone in a workspace there are none to protect, so
@@ -1555,7 +1847,7 @@ function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate }
       broadcast({ t: 'branch', ws: w.id, ...gitInfo.branchInfo(w.root) });   // let every client refresh the chip
     }
   }
-  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs });
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id });
   return { ok: true, session: s, notice };
 }
 
@@ -1891,7 +2183,299 @@ function needsByWorkspace() {
 }
 // Anything that resolves or files a need makes the memo stale; drop it rather than wait out the TTL.
 function invalidateNeedsAgg(id) { if (id) needsAgg.delete(id); else needsAgg.clear(); }
-function buildConsole(name, w, root) {
+// ── repo ingest (workspace-repo-ingest): clone → scan → review → accept. ──────────────────────
+// The whole design is the boundary between stages 2 and 3. `lib/repo-scan.js` is PURE — it opens
+// files and returns a PROPOSAL; it cannot write, shell, or decide. Every write in this pipeline
+// lives below, and there is exactly one of them that touches a record: the confirm handler.
+//
+// Proposals persist BESIDE state/workspaces.json, never inside the repository being scanned (R3):
+// a proposal that is never accepted must leave the clone byte-identical.
+const INGEST_CLONE_TIMEOUT_MS = Number(process.env.PMOS_INGEST_TIMEOUT_MS || 120_000);
+const INGEST_CREDENTIAL_NOTE = 'PMOS holds no GitHub credential and will not ask for one — the clone used the git credential helper this machine already has.';
+const GITHUB_REF = /^(?:https?:\/\/(?:www\.)?github\.com\/)?([A-Za-z0-9][\w.-]*)\/([A-Za-z0-9][\w.-]*?)(?:\.git)?\/?$/;
+
+function ingestPath(id) { return path.join(INGEST_DIR, id + '.json'); }
+function readProposal(id) {
+  if (!/^ing-\d+$/.test(String(id || ''))) return null;
+  try { return JSON.parse(fs.readFileSync(ingestPath(id), 'utf8')); } catch { return null; }
+}
+function writeProposal(pr) {
+  try { fs.mkdirSync(INGEST_DIR, { recursive: true }); fs.writeFileSync(ingestPath(pr.id), JSON.stringify(pr)); return null; }
+  catch (e) { warnWriteFail('state/ingest (the ingest proposal store)', e); return `the proposal could not be saved — ${String((e && e.code) || 'write failed')}`; }
+}
+function listProposals() {
+  let names = [];
+  try { names = fs.readdirSync(INGEST_DIR).filter((f) => /^ing-\d+\.json$/.test(f)); } catch { return []; }
+  return names.map((f) => readProposal(f.replace(/\.json$/, ''))).filter(Boolean)
+    .sort((a, b) => Number(a.id.slice(4)) - Number(b.id.slice(4)));
+}
+function nextIngestId() {
+  let max = 0;
+  try { for (const f of fs.readdirSync(INGEST_DIR)) { const m = /^ing-(\d+)\.json$/.exec(f); if (m && Number(m[1]) > max) max = Number(m[1]); } } catch {}
+  return 'ing-' + (max + 1);
+}
+// The three DERIVED fields the UI prints, computed from the module's own field names. The PRD
+// sketches `anchor:{source,value,evidence}`; the module returns declaredAnchor/guessedAnchor/why,
+// and the wire uses the module's names PLUS these — translating between the two shapes in four
+// places independently is exactly the drift this pipeline cannot afford.
+function ingestItemWire(row) {
+  return {
+    ...row,
+    anchor_state: row.declaredAnchor ? 'declared' : row.guessedAnchor ? 'guessed' : 'none',
+    anchor_value: row.declaredAnchor || row.guessedAnchor || null,
+    evidence: row.why == null ? null : row.why,
+    disposition: row.disposition || 'open',
+  };
+}
+function pushIngest(pr) { broadcast({ t: 'ingest', id: pr.id, stage: pr.stage, proposal: pr }); }
+
+// The clone. Asynchronous and OFF the request path (R1) — the POST returns an id immediately and
+// the result arrives over the socket. GIT_TERMINAL_PROMPT=0 is what turns a private repository
+// from a hang into a stated failure: git's own credential helper still runs, but nothing waits on
+// a username nobody is there to type.
+function startIngestClone(pr) {
+  const dir = path.join(CLONE_DIR, pr.id);
+  // 'error' and 'close' BOTH fire when the binary is missing, and `close` arrives with code null —
+  // which would overwrite "git is not on PATH" with "git exited with code null" and collapse two
+  // of the three failures R9 requires kept apart. First outcome wins; the rest are dropped.
+  // The guard is on the child's LIFECYCLE, not on fail() itself — the scan below runs after the
+  // clone has settled and must still be able to report its own failure.
+  let settled = false;
+  const fail = (error, extra) => {
+    const cur = readProposal(pr.id) || pr;
+    Object.assign(cur, { stage: 'review', ok: false, error, scanned_at: nowISO() }, extra || {});
+    cur.log.push({ level: 'error', path: null, message: error });
+    writeProposal(cur); pushIngest(cur);
+  };
+  try { fs.mkdirSync(CLONE_DIR, { recursive: true }); }
+  catch (e) { return fail(`the clone directory could not be created — ${String((e && e.code) || 'write failed')}`); }
+  // A re-run of the same id must not clone into a directory that already holds a tree.
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+
+  const env = { ...sessionEnv(), GIT_TERMINAL_PROMPT: '0' };
+  let child;
+  try {
+    child = spawn('git', ['clone', '--depth', '1', '--', pr.source.url, dir],
+      { env, stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch (e) {
+    // Thrown synchronously on some platforms; the same fact as the ENOENT below.
+    return fail('git is not on PATH — PMOS did not run a clone');
+  }
+  let stderr = '';
+  let timedOut = false;
+  child.stderr.on('data', (d) => { stderr = (stderr + String(d)).slice(-8000); });
+  const timer = setTimeout(() => { timedOut = true; try { child.kill('SIGKILL'); } catch {} }, INGEST_CLONE_TIMEOUT_MS);
+  if (timer.unref) timer.unref();
+  child.on('error', (e) => {
+    clearTimeout(timer);
+    if (settled) return;
+    settled = true;
+    // THREE distinct failures, and they must not collapse (R9): git absent is not a clone that
+    // failed, and neither is a clone that timed out.
+    if (e && e.code === 'ENOENT') return fail('git is not on PATH — PMOS did not run a clone');
+    fail(`git clone failed: ${String((e && e.message) || 'the clone could not be started')}`);
+  });
+  child.on('close', (code) => {
+    clearTimeout(timer);
+    if (settled) return;          // 'error' already reported the real reason — do not restate it worse
+    settled = true;
+    if (timedOut) {
+      return fail(`git clone timed out after ${Math.round(INGEST_CLONE_TIMEOUT_MS / 1000)}s — the clone did not complete and nothing was scanned`);
+    }
+    if (code !== 0) {
+      // git's OWN stderr line, verbatim. A rewritten error is a fact the PM cannot check.
+      const line = stderr.split('\n').map((l) => l.trim()).filter(Boolean).pop() || `git exited with code ${code}`;
+      const auth = /authentication|could not read Username|Permission denied|terminal prompts disabled|not found|403/i.test(stderr);
+      return fail(`git clone failed: ${line}`, auth ? { credential_note: INGEST_CREDENTIAL_NOTE } : null);
+    }
+    // The commit is read, never assumed. A proposal that cannot name the commit it scanned says
+    // null rather than a branch name standing in for one.
+    let commit = null;
+    try {
+      const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: dir, env, encoding: 'utf8' });
+      if (r.status === 0) commit = String(r.stdout || '').trim() || null;
+    } catch {}
+
+    const cur = readProposal(pr.id) || pr;
+    cur.stage = 'scan'; cur.source.commit = commit; cur.root = dir;
+    writeProposal(cur); pushIngest(cur);
+
+    let scan;
+    try { scan = repoScan.scanRepo(dir); }
+    catch (e) { return fail(`the scan failed — ${String((e && e.message) || 'error').slice(0, 160)}`); }
+    Object.assign(cur, {
+      stage: 'review', ok: scan.ok, error: scan.error, root: scan.root,
+      scanned_at: nowISO(),
+      log: cur.log.concat(scan.log),
+      unreadable: scan.unreadable,
+      initiatives: scan.initiatives.map(ingestItemWire),
+      adrs: scan.adrs.map((a) => ({ ...a, disposition: 'open' })),
+    });
+    writeProposal(cur); pushIngest(cur);
+  });
+}
+
+// The ONE record write in this pipeline. `parent_kr` is set into the LEADING frontmatter through
+// applyChange, whose contract is REFUSE ON MISMATCH — if the record moved between the scan and the
+// confirm, the write is rejected loudly rather than merged. Grep this file for `parent_kr`: this
+// function and the confirm handler are the only write site, which is R4 held structurally.
+function anchorEdit(text, anchor) {
+  const lines = text.split('\n');
+  if (lines[0].trim() !== '---') {
+    return { error: 'this record has no leading frontmatter block — PMOS will not add one during an import' };
+  }
+  let close = -1;
+  for (let i = 1; i < lines.length; i++) { if (lines[i].trim() === '---') { close = i; break; } }
+  if (close === -1) return { error: 'this record\'s leading frontmatter block is never closed — it is malformed, and PMOS will not guess where it ends' };
+  const head = lines.slice(0, close);
+  const at = head.findIndex((l) => /^parent_kr:/.test(l));
+  if (at !== -1) return { proposal: { before: head[at], after: `parent_kr: ${anchor}` } };
+  // No key at all: insert after `type:`, which D63 requires on every tracked record and which is
+  // therefore the one line guaranteed to exist exactly once in this block.
+  const t = head.findIndex((l) => /^type:/.test(l));
+  if (t === -1) return { error: 'this record declares no `type:` — PMOS has no anchor line to insert after and will not guess a position' };
+  return { proposal: { after: `\nparent_kr: ${anchor}` }, opts: { anchor: head[t] } };
+}
+
+// ── focus (workspace-focus): the three reads lib/focus.js cannot perform itself. ───────────────
+// focus.js is pure — it stats nothing and opens nothing. Two of its outputs are therefore SILENTLY
+// degraded when the caller does not supply an input, and both degradations are correct-looking:
+// without `skills` no ▶ delegate button ever appears anywhere, and without `budgetRegistry` every
+// budget cap reads `null`. They are supplied here, and their failures are passed through as
+// failures rather than as absences.
+
+// Every `.skill` file that EXISTS ON DISK under this repo's skills/ and build-skills/, as the
+// repo-relative paths focus.js matches against (`(?:build-)?skills/….skill`). One readdir per
+// directory per call — an offer PMOS cannot honour is worse than no offer, so the index is the
+// filesystem's answer and never a list of names we expect to be there.
+const SKILL_INDEX_MAX = 2000;
+function skillIndexFor(root) {
+  const out = [];
+  const walk = (dir, rel, depth) => {
+    if (depth > 4 || out.length >= SKILL_INDEX_MAX) return;
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (out.length >= SKILL_INDEX_MAX) return;
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name)) walk(path.join(dir, e.name), `${rel}/${e.name}`, depth + 1); }
+      else if (e.name.endsWith('.skill')) out.push(`${rel}/${e.name}`);
+    }
+  };
+  for (const base of ['skills', 'build-skills']) walk(path.join(root, base), base, 0);
+  return out;
+}
+
+// The health-budget registry (D59), parsed out of planning/okrs/health-budgets.md's own table.
+// {ok:false,error} and "not supplied" are DIFFERENT to focus.js — the first renders
+// budgets.state:'error', the second 'not-read' — so a failed read is never returned as an absence.
+const BUDGET_ROW = /^\|\s*`?health:([a-z0-9][\w-]*)`?\s*\|([^|]*)\|([^|]*)\|/i;
+function budgetRegistryFor(root) {
+  const rel = 'planning/okrs/health-budgets.md';
+  let text;
+  try { text = fs.readFileSync(path.join(root, rel), 'utf8'); }
+  catch (e) {
+    if (e && e.code === 'ENOENT') return { ok: false, error: `${rel} does not exist in this repository — no health budget declares a cap here` };
+    return { ok: false, error: `${rel} could not be read — ${String((e && e.code) || 'read failed')}` };
+  }
+  const budgets = [];
+  for (const line of text.split('\n')) {
+    const m = BUDGET_ROW.exec(line.trim());
+    if (!m) continue;
+    const cap = m[3].trim();
+    budgets.push({ id: `health:${m[1].toLowerCase()}`, covers: m[2].trim() || null, cap: cap || null });
+  }
+  // A file that parsed to nothing is reported as read-and-empty, not as an error: a repo may
+  // legitimately declare no budgets, and the caps column is the only thing being claimed here.
+  return { ok: true, budgets, path: rel };
+}
+
+// One entry per DISTINCT repo_key — a PRODUCT, not a working tree. Several worktrees of one repo
+// are one product with one board, and counting them separately is what put the same initiative in
+// the queue three times. boardCache.board() ONLY (§6.8): consoleState.workflow() is ~30s and
+// synchronous, and on a request path it freezes every PTY socket for the whole half minute.
+function focusProducts() {
+  const trees = wsList();
+  const groups = new Map();   // repo_key -> { id, name, trees[] }
+  for (const t of trees) {
+    const key = t.repo_key || t.root;
+    if (!groups.has(key)) groups.set(key, { id: key, name: t.repo_name || t.name, trees: [] });
+    groups.get(key).trees.push(t);
+  }
+  const rows = sessionList();
+  return [...groups.values()].map((g) => {
+    // The tree whose root IS the repo — the main worktree — is the one whose planning/ and okf/ are
+    // canonical. Absent it (only linked worktrees registered), the first registered tree stands in.
+    const lead = g.trees.find((t) => path.resolve(t.root) === path.resolve(g.id)) || g.trees[0];
+    const w = workspaces.get(lead.id) || null;
+    const root = w ? w.root : lead.root;
+    const ids = new Set(g.trees.map((t) => t.id));
+    let needs;
+    try { needs = needsResult(w); }
+    catch (e) { needs = { ok: false, error: 'the needs-you queue could not be read — ' + String((e && e.code) || 'error').slice(0, 60) }; }
+    let spine;
+    try { spine = surfaceSpine(root); }
+    catch (e) { spine = { unreadable: 'the spine could not be derived — ' + String((e && e.message) || 'error').slice(0, 120) }; }
+    return {
+      id: g.id, name: g.name,
+      board: boardCache.board(root),
+      needs,
+      spine,
+      // Partitioned by each row's OWN `ws`, because focus.js matches sessions to products by id and
+      // a session's `ws` is a working-tree id, not a repo key — the join has to happen here.
+      sessions: rows.filter((s) => ids.has(s.ws)),
+    };
+  });
+}
+
+// ── workflow templates (jira-handoff R13). ────────────────────────────────────────────────────
+// A DECLARED template is a file a human wrote. Nothing derives from it — the engine
+// (scripts/workflow-state.js) builds one fixed ladder per lane and never reads `flow:` — so the
+// stage list must come out of the document's own body and `declared:true` is shipped so the client
+// can label the group without inventing the word.
+const STAGE_CHAIN = /([a-z][a-z0-9_-]{1,24})(?:\s*(?:→|->)\s*([a-z][a-z0-9_-]{1,24}))+/i;
+function templateStages(text, fm) {
+  // A declared `stages:` list in frontmatter wins — it is the document saying so directly.
+  const declared = fm && typeof fm.stages === 'string' ? fm.stages : null;
+  const line = declared || (STAGE_CHAIN.test(text) ? STAGE_CHAIN.exec(text)[0] : null);
+  if (!line) return [];   // never a default six-stage list: that would be this server declaring it
+  return line.split(/\s*(?:→|->|,)\s*/).map((s) => s.trim().replace(/^[`'"]|[`'"]$/g, ''))
+    .filter((s) => /^[a-z][a-z0-9_-]*$/i.test(s));
+}
+function workflowTemplates(root) {
+  const rel = 'planning/workflows';
+  const dir = path.join(root, rel);
+  let ents;
+  try { ents = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch (e) {
+    // ABSENT is calm and stated — most repositories have none — and is not the same answer as
+    // "the directory is there and PMOS could not look inside it".
+    if (e && e.code === 'ENOENT') return { ok: true, empty: true, dir: rel, templates: [], absent: true };
+    return { ok: false, error: `${rel} could not be listed — ${String((e && e.code) || 'read failed')}` };
+  }
+  const files = ents.filter((e) => !e.isDirectory() && /\.md$/i.test(e.name)).map((e) => e.name).sort();
+  const templates = [];
+  for (const nm of files) {
+    if (nm === 'index.md' || nm === 'log.md') continue;   // OKF-reserved, never a concept document
+    let text;
+    try { text = fs.readFileSync(path.join(dir, nm), 'utf8'); }
+    catch (e) { return { ok: false, error: `${rel}/${nm} could not be read — ${String((e && e.code) || 'read failed')}` }; }
+    const fm = fmParse.parseLeadingFrontmatter(text) || {};
+    // D63 titles are quoted in frontmatter; the quotes are syntax, not part of the title. `null`
+    // rather than the filename when there is none — a filename standing in for a title is a title
+    // the document does not have.
+    const title = String(fm.title == null ? '' : fm.title).trim().replace(/^["']|["']$/g, '').trim();
+    templates.push({
+      id: nm.replace(/\.md$/i, ''), path: `${rel}/${nm}`,
+      title: title || null,
+      stages: templateStages(text, fm),
+      declared: true,
+    });
+  }
+  if (!templates.length) return { ok: true, empty: true, dir: rel, templates: [] };
+  return { ok: true, empty: false, dir: rel, templates };
+}
+
+function buildConsole(name, w, root, params) {
   const stateDir = stateDirFor(w);
   const snapshotDir = latestSnapshotDir(root);
   if (name === 'needs') return needsResult(w);
@@ -1905,6 +2489,75 @@ function buildConsole(name, w, root) {
   // child; the payload carries `as_of` / `stale` / `pending` so the client can say how old the
   // answer is instead of implying it is current.
   if (name === 'workflow') return boardCache.board(w ? w.root : root);
+  // ONE initiative's ladder. The board caps itself at what is in flight and reports the rest as
+  // `hidden`; a panel asked about a named initiative must not read that cap as "no record", so it
+  // derives the one it was asked for. Single engine run — safe on the request path, unlike a board.
+  if (name === 'ladder') return consoleState.ladder({ root: w ? w.root : root, id: params && params.get('id') });
+  // The PM spine belongs to the console family, not the deliverable family: it is read-only
+  // file-mode state and it owes the same honesty contract — a failed read renders RED, never a
+  // green empty tree (R5). It reads the OPENED workspace's repo for the same reason the ladder
+  // does — objectives, budgets and initiative records are properties of that repo.
+  if (name === 'spine') {
+    const s = surfaceSpine(w ? w.root : root);
+    if (s.unreadable) return { ok: false, error: s.unreadable };
+    const placed = s.objectives.reduce((n, o) =>
+      n + o.krs.reduce((m, k) => m + k.initiatives.length, 0) + (o.direct ? o.direct.length : 0), 0)
+      + s.budgets.reduce((n, b) => n + b.initiatives.length, 0);
+    // `empty` is a SUCCESSFUL read of genuinely nothing — a repo with no initiative records at all.
+    // It is a supported thing to point the workspace at, so it renders calm, not red.
+    return { ok: true, empty: placed === 0 && s.unanchored.length === 0, ...s };
+  }
+  // ── focus (workspace-focus). CROSS-PRODUCT: `ws` is accepted and IGNORED. ──
+  // Focus joins every registered workspace, so scoping it to the selected tree would hide the one
+  // item that is actually blocking the PM behind whichever repo they happened to be standing in.
+  if (name === 'focus') {
+    const products = focusProducts();
+    // The skill index is per-product and unioned: focus.js matches a step's `next` against
+    // repo-relative paths, and a skill that exists in one repo is a real offer for that repo's
+    // ladder. Supplying `[]` (rather than nothing) when no repo has any is deliberate — it means
+    // "we looked and found none", which correctly yields no offers, not "we did not look".
+    // `product.id` IS the repo's main-worktree directory (repoIdentity's key), so it is the root to
+    // read — no second lookup, and no chance of indexing a different tree's skills.
+    const skills = new Set();
+    for (const pr of products) for (const s of skillIndexFor(pr.id)) skills.add(s);
+    // ONE registry, read from the home repo when there is one — health budgets are a PMOS-wide
+    // declaration (D59), and every product's spine is matched against the same caps.
+    const regRoot = HOME_ENABLED ? SELF_ROOT : (products.length ? products[0].id : SELF_ROOT);
+    const view = focus.buildFocus({
+      products,
+      sessions: sessionList(),
+      skills: [...skills],
+      budgetRegistry: budgetRegistryFor(regRoot),
+    });
+    return { ok: true, ...view };
+  }
+  // ── handoff (workspace-jira-handoff R1). ──
+  // The record's LEADING frontmatter, which no existing payload carries, parsed by the real
+  // parser — a hand-rolled regex here would be a second opinion about what a record declares.
+  // `links.connected` is false on every code path readLinks has; there is no argument that
+  // changes it and none is passed.
+  if (name === 'handoff') {
+    const id = params && params.get('id');
+    if (!id) return { ok: false, error: 'an initiative id is required', http_status: 400 };
+    // Same path guard as every other read on this surface — an id is a filename, not a path.
+    if (!/^[A-Za-z0-9][\w.-]*$/.test(id)) return { ok: false, error: 'that initiative id is not a record name', http_status: 400 };
+    const rel = `planning/initiatives/${id}.md`;
+    const file = path.join(w ? w.root : root, 'planning', 'initiatives', `${id}.md`);
+    let text;
+    try { text = fs.readFileSync(file, 'utf8'); }
+    catch (e) {
+      // A record that does not exist is NOT a failed read — the panel already has a "no record"
+      // state for it. Anything else (EACCES, EISDIR, EIO) is PMOS failing to look, and is red.
+      if (e && e.code === 'ENOENT') return { ok: true, id, record: rel, links: null, absent: true };
+      return { ok: false, error: `${rel} could not be read — ${String((e && e.code) || 'read failed')}` };
+    }
+    let links;
+    try { links = handoff.readLinks(fmParse.parseLeadingFrontmatter(text)); }
+    catch (e) { return { ok: false, error: `${rel} — ${String((e && e.message) || 'the frontmatter could not be parsed').slice(0, 160)}` }; }
+    return { ok: true, id, record: rel, links };
+  }
+  // ── workflow templates (jira-handoff R13). ──
+  if (name === 'workflows') return workflowTemplates(w ? w.root : root);
   return { ok: false, error: 'unknown console surface: ' + name };
 }
 
@@ -2044,7 +2697,7 @@ function serveFile(res, file, type, noCache) {
   fs.readFile(file, (err, buf) => {
     if (err) { res.writeHead(404); res.end('not found'); return; }
     const headers = { 'Content-Type': type || TYPES[path.extname(file)] || 'application/octet-stream' };
-    // The app SHELL (index.html + app.js) must revalidate every load: without this a tab left open
+    // The app SHELL (index.html + the /pm/ module graph) must revalidate every load: without this a tab left open
     // across a `git merge` + server restart keeps running the pre-merge JS, so a fix that IS being
     // served never reaches the screen. `no-cache` = "always revalidate", not "never store".
     if (noCache) headers['Cache-Control'] = 'no-cache';
@@ -2065,9 +2718,13 @@ async function handleRequest(req, res) {
   const p = url.pathname;
 
   if (p === '/' || p === '/index.html') return serveFile(res, path.join(PUB, 'index.html'), null, true);
-  if (p === '/app.js') return serveFile(res, path.join(PUB, 'app.js'), null, true);
+  // NB: there is no `/app.js` route. The single-file front end that owned it (public/app.js +
+  // public/styles.css) was RETIRED with the four-panel design — the shell is index.html plus the
+  // /pm/ module graph below, and one front end is the point. A stray <script src="/app.js"> now
+  // 404s loudly rather than silently resurrecting a second, diverging surface.
   if (p === '/lib/preview-kind.js') return serveFile(res, path.join(__dirname, 'lib', 'preview-kind.js'));
   if (p === '/lib/layout.js') return serveFile(res, path.join(__dirname, 'lib', 'layout.js'));
+  if (p === '/lib/mobile-nav.js') return serveFile(res, path.join(__dirname, 'lib', 'mobile-nav.js'));
   if (p === '/lib/session-state.js') return serveFile(res, path.join(__dirname, 'lib', 'session-state.js'));
   // The editor computes its live diff with the SAME module the server saves through, so what the PM
   // sees while typing and what gets written cannot disagree. NB: /lib/ is an explicit allowlist, not
@@ -2075,7 +2732,19 @@ async function handleRequest(req, res) {
   // client feature that depends on it fails in a way no server-side test can see.
   if (p === '/lib/apply-change.js') return serveFile(res, path.join(__dirname, 'lib', 'apply-change.js'));
   if (p === '/lib/related-docs.js') return serveFile(res, path.join(__dirname, 'lib', 'related-docs.js'));
-  if (p === '/styles.css') return serveFile(res, path.join(PUB, 'styles.css'));
+  // …and no `/styles.css` route either: the token layer and every component rule now ship as
+  // /pm/tokens.css + /pm/mobile.css through the /pm/ directory route below.
+  // Every browser asks for /favicon.ico unprompted. Without a route it 404s on every load, which
+  // puts a permanent red line in the console and in this suite's `page errors seen` list — noise
+  // that trains you to ignore the one place a real client-side failure would show up. An inline SVG
+  // answers it with no asset to ship: the PMOS mark, sized to work at 16px.
+  if (p === '/favicon.ico' || p === '/favicon.svg') {
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">` +
+      `<rect width="16" height="16" rx="3" fill="#111"/>` +
+      `<path d="M4 12V4h3.2a2.4 2.4 0 010 4.8H6" stroke="#fff" stroke-width="1.6" fill="none"/></svg>`;
+    res.writeHead(200, { 'Content-Type': 'image/svg+xml', 'Cache-Control': 'max-age=86400' });
+    return res.end(svg);
+  }
   // xterm assets straight from node_modules (offline; no CDN)
   if (p === '/vendor/xterm.js') return serveFile(res, path.join(XROOT, 'xterm', 'lib', 'xterm.js'));
   if (p === '/vendor/xterm.css') return serveFile(res, path.join(XROOT, 'xterm', 'css', 'xterm.css'));
@@ -2086,7 +2755,28 @@ async function handleRequest(req, res) {
   // because the terminal renders bold — with only the regular face the browser synthesises it.
   if (p === '/vendor/space-grotesk-var.woff2') return serveFile(res, path.join(PUB, 'vendor', 'space-grotesk-var.woff2'));
   if (p === '/vendor/ibm-plex-mono-400.woff2') return serveFile(res, path.join(PUB, 'vendor', 'ibm-plex-mono-400.woff2'));
+  // 500 joined 400/700 with the four-panel design, whose section labels and pills are medium-weight
+  // mono. Without the face the browser synthesises it, and a synthesised weight is exactly the kind
+  // of difference the design-parity comparator reports and a human eye does not.
+  if (p === '/vendor/ibm-plex-mono-500.woff2') return serveFile(res, path.join(PUB, 'vendor', 'ibm-plex-mono-500.woff2'));
   if (p === '/vendor/ibm-plex-mono-700.woff2') return serveFile(res, path.join(PUB, 'vendor', 'ibm-plex-mono-700.woff2'));
+  // ── the four-panel front end (public/pm/) ──────────────────────────────────────────────────────
+  // A DIRECTORY route, deliberately, where /lib/ above is an allowlist. The allowlist's own comment
+  // records why it is a trap: a file missing from it 404s silently and the feature that needed it
+  // fails somewhere no server-side test looks. That cost is tolerable for six stable modules and is
+  // not tolerable for a front end split into fifteen, where every new module would be one forgotten
+  // line away from a blank panel. The traversal guard is what makes the directory form safe: the
+  // resolved path must still sit inside PM_DIR, so '..' segments and absolute-looking names cannot
+  // reach a file outside it. Extension-restricted as well — this route serves code and styles, not
+  // whatever else happens to land in the folder.
+  if (p.startsWith('/pm/')) {
+    const rel = p.slice('/pm/'.length);
+    const file = path.resolve(PM_DIR, rel);
+    if (!file.startsWith(PM_DIR + path.sep) || !['.js', '.css', '.json'].includes(path.extname(file))) {
+      res.writeHead(404); return res.end('not found');
+    }
+    return serveFile(res, file, null, true);
+  }
 
   if (p === '/api/workspaces' && req.method === 'GET') return json(res, { workspaces: wsList() });
   if (p === '/api/workspaces' && req.method === 'POST') {
@@ -2145,6 +2835,191 @@ async function handleRequest(req, res) {
     if (!isDir(root)) return json(res, { ok: false, error: `not a directory: ${root}` }, 400);
     return json(res, { ok: true, root });
   }
+  // ── repo ingest (workspace-repo-ingest R1/R2/R9). ────────────────────────────────────────────
+  if (p === '/api/ingest' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    // R2 enforced in CODE, not only in copy: a local folder is REGISTERED (POST /api/workspaces)
+    // and nothing is imported from it. Accepting `folder` here and quietly registering it would
+    // make the two paths indistinguishable to anything but the copy under the radio button.
+    if (body.source === 'folder' || body.source === 'local') {
+      return json(res, { ok: false, error: 'a local folder is registered, never ingested — nothing is imported from a bare folder' }, 400);
+    }
+    if (body.source !== 'github') return json(res, { ok: false, error: 'source must be "github"' }, 400);
+    const ref = String(body.ref == null ? '' : body.ref).trim();
+    if (!ref) return json(res, { ok: false, error: 'a repository reference is required' }, 400);
+    const m = GITHUB_REF.exec(ref);
+    if (!m) return json(res, { ok: false, error: `"${ref.slice(0, 80)}" is not a GitHub repository reference — give owner/name or https://github.com/owner/name` }, 400);
+    const slug = `${m[1]}/${m[2]}`;
+    const pr = {
+      id: nextIngestId(), stage: 'acquire',
+      source: { kind: 'github', ref: slug, url: `https://github.com/${slug}.git`, commit: null },
+      clone_dir: `state/clones/`, scanned_at: null,
+      ok: true, error: null, root: null,
+      log: [{ level: 'info', path: null, message: `cloning ${slug} — read-only; nothing is written into this repository or into PMOS until an item is confirmed` }],
+      unreadable: [], initiatives: [], adrs: [],
+    };
+    pr.clone_dir = `state/clones/${pr.id}`;
+    const err = writeProposal(pr);
+    if (err) return json(res, { ok: false, error: err }, 500);
+    pushIngest(pr);
+    // Returns IMMEDIATELY. The clone runs off the request path and reports over the socket.
+    startIngestClone(pr);
+    return json(res, { ok: true, id: pr.id, stage: pr.stage });
+  }
+  if (p === '/api/ingest' && req.method === 'GET') {
+    const id = url.searchParams.get('id');
+    if (id) {
+      const pr = readProposal(id);
+      if (!pr) return json(res, { ok: false, error: 'no such ingest' });
+      return json(res, { ok: true, proposal: pr });
+    }
+    return json(res, { ok: true, proposals: listProposals().filter((x) => x.stage !== 'closed') });
+  }
+  if (p === '/api/ingest/confirm' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    // ONE item. There is no array form, no `items`, no `all` — the tedium IS the gate (R4). A
+    // bulk confirm is how a dozen guessed anchors land on the board with every check green.
+    if (Array.isArray(body.item) || body.items != null || body.all != null) {
+      return json(res, { ok: false, error: 'confirmation is per item' }, 400);
+    }
+    const pr = readProposal(body.id);
+    if (!pr) return json(res, { ok: false, error: 'no such ingest' }, 400);
+    const item = String(body.item == null ? '' : body.item);
+    const row = (pr.initiatives || []).find((r) => r.id === item);
+    if (!row) return json(res, { ok: false, error: `this proposal has no item "${item.slice(0, 60)}"` }, 400);
+    // The anchor comes from the PM's action and nowhere else. There is no code path in which a
+    // `guessedAnchor` reaches `parent_kr` without an explicit request carrying it.
+    const anchor = String(body.anchor == null ? '' : body.anchor).trim();
+    if (!anchor) return json(res, { ok: false, error: 'an anchor is required — a guess is not a declaration and D59 rejects unanchored work' }, 400);
+    if (!pr.root) return json(res, { ok: false, error: 'this proposal has no scanned repository — nothing was cloned, so there is nothing to write to' }, 409);
+    const full = path.resolve(pr.root, row.path);
+    if (!insideRoot(pr.root, full)) return json(res, { ok: false, error: 'that record is outside the scanned repository' }, 400);
+
+    // The resolver's verdict is computed and reported BEFORE the write, so the PM is told whether
+    // the anchor they chose names anything this repository declares — not after the fact.
+    let resolves = false, resolverNote = 'the anchor resolver (scripts/anchor-resolve.js) is not present in this install — whether this anchor resolves was not checked';
+    const A = anchorLib();
+    if (A) {
+      try {
+        const r = A.resolveAnchor(anchor, A.parseOkrIndex(pr.root), A.readBudgets(pr.root));
+        resolves = r.status === 'resolved';
+        resolverNote = r.reason || `anchor status: ${r.status}`;
+      } catch (e) { resolverNote = `the anchor could not be resolved — ${String((e && e.message) || 'error').slice(0, 120)}`; }
+    }
+
+    let current;
+    try { current = fs.readFileSync(full, 'utf8'); }
+    catch (e) { return json(res, { ok: false, error: `${row.path} could not be read — ${String((e && e.code) || 'read failed')}` }, 409); }
+    const edit = anchorEdit(current, anchor);
+    if (edit.error) return json(res, { ok: false, error: `${row.path} — ${edit.error}` }, 409);
+    const applied = applyChange.applyChange(current, edit.proposal, edit.opts);
+    if (!applied.ok) {
+      // applyChange's OWN refusal reason — the record moved between the scan and the confirm, and
+      // a merged-anyway write is a diff the PM never saw.
+      return json(res, { ok: false, error: `${row.path} — ${applied.detail || applied.reason}` }, 409);
+    }
+    try { fs.writeFileSync(full, applied.text); }
+    catch (e) { return json(res, { ok: false, error: `${row.path} could not be written — ${String((e && e.code) || 'write failed')}` }, 409); }
+    row.disposition = 'confirmed';
+    row.declaredAnchor = anchor; row.guessedAnchor = null;
+    row.anchor_state = 'declared'; row.anchor_value = anchor;
+    row.why = `confirmed by the PM on ${nowISO()} — written into ${row.path} as \`parent_kr: ${anchor}\``;
+    row.evidence = row.why;
+    const werr = writeProposal(pr);
+    pushIngest(pr);
+    if (werr) return json(res, { ok: false, error: `${anchor} was written into ${row.path}, but ${werr} — the proposal on screen is now behind the file` }, 500);
+    return json(res, { ok: true, path: row.path, anchor, resolves, resolver_note: resolverNote });
+  }
+  if (p === '/api/ingest/dismiss' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const pr = readProposal(body.id);
+    if (!pr) return json(res, { ok: false, error: 'no such ingest' }, 400);
+    const row = (pr.initiatives || []).find((r) => r.id === String(body.item == null ? '' : body.item));
+    if (!row) return json(res, { ok: false, error: `this proposal has no item "${String(body.item || '').slice(0, 60)}"` }, 400);
+    row.disposition = 'dismissed';
+    const err = writeProposal(pr);
+    if (err) return json(res, { ok: false, error: err }, 500);
+    pushIngest(pr);
+    return json(res, { ok: true });
+  }
+  if (p === '/api/ingest/adr' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const pr = readProposal(body.id);
+    if (!pr) return json(res, { ok: false, error: 'no such ingest' }, 400);
+    const disposition = body.disposition;
+    if (disposition !== 'accepted' && disposition !== 'superseded') {
+      return json(res, { ok: false, error: 'disposition must be "accepted" or "superseded"' }, 400);
+    }
+    const rel = String(body.path == null ? '' : body.path);
+    const adr = (pr.adrs || []).find((a) => a.path === rel);
+    if (!adr) return json(res, { ok: false, error: `this proposal has no ADR at "${rel.slice(0, 80)}"` }, 400);
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace to accept this ADR into' }, 400);
+
+    let wrote = null;
+    if (disposition === 'accepted') {
+      if (!pr.root) return json(res, { ok: false, error: 'this proposal has no scanned repository — there is no file to copy' }, 409);
+      const src = path.resolve(pr.root, rel);
+      if (!insideRoot(pr.root, src)) return json(res, { ok: false, error: 'that ADR is outside the scanned repository' }, 400);
+      // The RECEIVING repo's own adr/ directory. PMOS does not invent one: a repository with no
+      // OKF bundle has nowhere an ADR belongs, and creating a tree during an import would be this
+      // server deciding where another repo's knowledge lives.
+      const dirs = findDirsNamed(path.join(w.root, 'okf'), 'adr', 3);
+      if (!dirs.length) {
+        return json(res, { ok: false, error: `“${w.name}” has no \`adr/\` directory under okf/ — PMOS will not create one during an import; make the directory and accept again` }, 409);
+      }
+      let text;
+      try { text = fs.readFileSync(src, 'utf8'); }
+      catch (e) { return json(res, { ok: false, error: `${rel} could not be read — ${String((e && e.code) || 'read failed')}` }, 409); }
+      const name = path.basename(rel);
+      const dest = path.join(dirs[0], name);
+      // Never overwrite. An ADR of that name already there is a collision only a human can settle.
+      if (fs.existsSync(dest)) {
+        return json(res, { ok: false, error: `${path.relative(w.root, dest)} already exists — PMOS will not overwrite an ADR during an import` }, 409);
+      }
+      // The PROVENANCE goes into the FILE. The `ingested` badge is derived from `ingested_from`
+      // being present in the document — never from a stored flag — so a badge cannot outlive the
+      // fact it claims, and a copy someone moves by hand carries its own origin with it.
+      // The scan only proposes a file that already parsed with a `type: ADR` frontmatter block, so
+      // the two lines go inside the block that is known to be there rather than in a new one.
+      const stamp = `ingested_from: ${pr.source.ref}@${pr.source.commit || 'unknown-commit'}\ningested_at: ${nowISO().slice(0, 10)}`;
+      const lines = text.split('\n');
+      if (lines[0].trim() !== '---') {
+        return json(res, { ok: false, error: `${rel} has no leading frontmatter block — PMOS cannot record where it came from, and will not import a document it cannot stamp` }, 409);
+      }
+      lines.splice(1, 0, stamp);
+      try { fs.writeFileSync(dest, lines.join('\n')); }
+      catch (e) { return json(res, { ok: false, error: `${path.relative(w.root, dest)} could not be written — ${String((e && e.code) || 'write failed')}` }, 409); }
+      wrote = path.relative(w.root, dest);
+    }
+    // The disposition itself is a decision record, appended to the workspace's own file-mode
+    // state, keyed by ADR path. It is NOT written to acceptances.jsonl: that file is the PM
+    // Acceptance Gate's log and metrics.py counts its rows for the north star — filing an import
+    // decision there would inflate a metric with something that was never an agent run.
+    const d = stateDirFor(w, { create: true });
+    if (!d) return json(res, { ok: false, error: `the disposition could not be recorded — “${w.name}” has no file-mode state directory and PMOS will not create one in a repository of unknown shape`, wrote }, 500);
+    const rec = { at: nowISO(), date: nowISO().slice(0, 10), kind: 'adr', adr_path: rel,
+      disposition, ingest: pr.id, source: `${pr.source.ref}@${pr.source.commit || 'unknown-commit'}`,
+      wrote, workspace: w.name, root: w.root, pm: true };
+    try { fs.appendFileSync(path.join(d, 'ingest.jsonl'), JSON.stringify(rec) + '\n'); }
+    catch (e) {
+      warnWriteFail('ingest.jsonl (ADR dispositions)', e);
+      return json(res, { ok: false, error: 'the disposition could not be recorded — the file-mode state directory is unwritable; the decision was NOT saved', wrote }, 500);
+    }
+    adr.disposition = disposition;
+    const err = writeProposal(pr);
+    if (err) return json(res, { ok: false, error: err, wrote }, 500);
+    pushIngest(pr);
+    return json(res, { ok: true, wrote });
+  }
   if (p === '/api/fs/list') {
     const listing = fsList(url.searchParams.get('path'));
     if (!listing) return json(res, { ok: false, error: 'not a directory' }, 404);
@@ -2224,10 +3099,64 @@ async function handleRequest(req, res) {
       skill: { id: built.slug, label: built.label, skill: built.slug,
         description: built.description, output: built.output, source: 'user' } });
   }
+  // ── profiles (workspace-profiles R1/R2/R4). ──────────────────────────────────────────────────
+  // Four states, mapped straight from readProfiles() and NEVER collapsed: the directory does not
+  // exist (calm, path named) · it exists and holds nothing (a successful read of nothing, also
+  // calm, different words) · it holds descriptors, some of which are broken (both lists ship —
+  // one bad file must not turn the surface into a stated absence) · it could not be read (RED).
+  //
+  // `env` values are absent from this payload BY CONSTRUCTION (profileWire). An overlay is where a
+  // credential lives, and D08's discipline covers anything the browser receives; `env_keys` exists
+  // so the pane can say WHAT was applied without shipping what it was.
+  if (p === '/api/profiles' && req.method === 'GET') {
+    const read = readProfilesNow();
+    return json(res, {
+      ok: read.ok !== false,
+      absent: !!read.absent,
+      dir: read.dir,
+      profiles: (read.profiles || []).map((x) => profileWire(x, read)),
+      broken: (read.broken || []).map((b) => ({ file: b.file, error: b.error })),
+      prefs: readPrefs(),
+      error: read.error || null,
+    });
+  }
+  if (p === '/api/profiles/prefer' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const agent = typeof body.agent === 'string' ? body.agent.trim() : '';
+    if (!agent) return json(res, { ok: false, error: 'an agent name is required' }, 400);
+    // "Unknown agent" has to mean something CHECKABLE, and PMOS keeps no agent registry — the
+    // roster is derived from live sessions, which is a client-side fact. What the server can check
+    // is the only thing that matters here: whether it could ever start that agent. A preference
+    // for a CLI that is not on this machine would preselect the composer for something that
+    // cannot spawn. `shell` is the one built-in kind and has no binary of its own.
+    if (agent !== 'shell' && !commandExists(agent)) {
+      return json(res, { ok: false, error: `“${agent.slice(0, 40)}” is not on PATH — PMOS will not remember a preference for an agent it cannot start` }, 400);
+    }
+    // PMOS does not remember a preference for a descriptor it cannot read. The preference is its
+    // OWN memory (it preselects the composer and starts nothing), so a stored id that resolves to
+    // nothing would silently preselect a chip that is not on screen.
+    const pres = resolveProfileForSpawn(body.profile);
+    if (!pres.ok) return json(res, { ok: false, error: pres.error }, 400);
+    const prefs = readPrefs();
+    if (pres.id == null) delete prefs[agent]; else prefs[agent] = pres.id;
+    const err = writePrefs(prefs);
+    if (err) return json(res, { ok: false, error: err }, 500);
+    return json(res, { ok: true, prefs });
+  }
   if (p === '/api/schedules' && req.method === 'GET') {
     const wsFilter = getWs(url.searchParams.get('ws'));
     const id = wsFilter ? wsFilter.id : null;
-    const list = readSchedules().filter((s) => !id || s.ws === id).map((s) => ({ ...s, next: scheduleLogic.nextRun(s) }));
+    const list = readSchedules().filter((s) => !id || s.ws === id).map((s) => {
+      // `profile_applies` is the difference between "no profile was chosen" and "a profile could
+      // not apply here at all": a skill-kind task runs IN THIS PROCESS and never creates a PTY, so
+      // the detail row states that instead of offering a control that would do nothing (R8.3).
+      const t = taskById(s.task || s.skill);
+      return { ...s, next: scheduleLogic.nextRun(s),
+        profile: s.profile == null ? null : s.profile,
+        profile_applies: !!(t && t.kind === 'agent') };
+    });
     return json(res, { schedules: list, now: nowISO() });
   }
   if (p === '/api/schedules' && req.method === 'POST') {
@@ -2236,7 +3165,11 @@ async function handleRequest(req, res) {
     const norm = scheduleLogic.normalizeSchedule(body);
     if (!norm.ok) return json(res, { ok: false, error: norm.error }, 400);
     const w = getWs(body.ws);
-    const sched = { id: 'sc-' + Date.now().toString(36), ws: w ? w.id : wsId(SELF_ROOT), ...norm.schedule, lastRun: null, lastStatus: null };
+    // A profile named on a schedule is checked NOW, not at fire time — the PM is here to be told.
+    const pres = resolveProfileForSpawn(body.profile);
+    if (!pres.ok) return json(res, { ok: false, error: pres.error }, 400);
+    const sched = { id: 'sc-' + Date.now().toString(36), ws: w ? w.id : wsId(SELF_ROOT), ...norm.schedule,
+      profile: pres.id, lastRun: null, lastStatus: null };
     sched.nextRun = scheduleLogic.nextRun(sched);
     const list = readSchedules(); list.unshift(sched); writeSchedules(list);
     return json(res, { ok: true, schedule: sched });
@@ -2247,6 +3180,13 @@ async function handleRequest(req, res) {
     if (!s) return json(res, { ok: false, error: 'no such schedule' }, 404);
     if (typeof body.enabled === 'boolean') s.enabled = body.enabled;
     for (const k of ['name', 'cadence', 'day', 'dayOfMonth', 'time', 'task', 'skill']) if (body[k] != null) s[k] = body[k];
+    // `profile` is settable to null (clear it) as well as to an id, so it is checked for PRESENCE
+    // of the key rather than for a non-null value — the other fields above cannot be cleared.
+    if ('profile' in body) {
+      const pres = resolveProfileForSpawn(body.profile);
+      if (!pres.ok) return json(res, { ok: false, error: pres.error }, 400);
+      s.profile = pres.id;
+    }
     s.nextRun = scheduleLogic.nextRun(s); writeSchedules(list);
     return json(res, { ok: true, schedule: s });
   }
@@ -2375,9 +3315,96 @@ async function handleRequest(req, res) {
     const w = getWs(url.searchParams.get('ws'));
     const root = w ? w.root : SELF_ROOT;
     let out;
-    try { out = buildConsole(name, w, root); }
+    try { out = buildConsole(name, w, root, url.searchParams); }
     catch (e) { out = { ok: false, error: 'console read failed: ' + String((e && e.message) || 'error').slice(0, 120) }; }
-    return json(res, { name, ...out });
+    // A surface may name an HTTP status for a MALFORMED REQUEST only (400 — a missing required
+    // param). Every discriminated READ result stays 200, including {ok:false}: the client's
+    // honest-state rendering is driven by the body, and a transport code cannot carry the reason.
+    // Stripped by spreading rather than deleting — some surfaces return frozen objects.
+    const code = (out && Number.isFinite(out.http_status)) ? out.http_status : 200;
+    if (out && out.http_status != null) { out = { ...out }; delete out.http_status; }
+    return json(res, { name, ...out }, code);
+  }
+  // ── ONE initiative, assembled (the four-panel surface). ────────────────────────────────────
+  // Panel 3 needs the record, its artifacts, its ladder, its external references, its anchor and
+  // its sessions to answer a single question about a single initiative. Every one of those is
+  // already produced somewhere here; what did not exist was the JOIN, so each client had to make
+  // it — four round-trips per selection, and four chances for two surfaces to disagree about one
+  // record. This route calls the SAME producers the existing endpoints call and joins them once.
+  // The existing endpoints are deliberately unchanged: other surfaces still read them.
+  //
+  // GET  → the assembled payload.
+  // POST → append one declaration to a file-mode store (see fourPanel's header for why a link is
+  //        a declaration and never an outbound call).
+  if (p === '/api/initiative' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    const root = w ? w.root : SELF_ROOT;
+    const id = url.searchParams.get('id') || '';
+    // An id is a filename, not a path — the same guard the handoff surface applies, and the reason
+    // this route can join a path without a traversal check at every use site.
+    if (!fourPanel.validId(id)) {
+      return json(res, { ok: false, error: 'an initiative id is required, and it must be a record name' }, 400);
+    }
+    const engine = consoleState.loadEngine();
+    if (!engine.ok) return json(res, { ok: false, id, error: engine.error });
+    const L = engine.engine.layout(root);
+    // The ENGINE's frontmatter parser, not the workspace's — see lib/four-panel.js on why the two
+    // disagree and why this endpoint's `frontmatter` has to agree with its own `ladder`.
+    const rec = fourPanel.readRecord({ root, dir: L.initiatives, id, parse: engine.engine.parseLeadingFrontmatter });
+    // A record that would not READ is the one fact the panel must show, and it is the whole
+    // answer: deriving a ladder over a file that could not be parsed would be deriving over
+    // nothing, and reporting the result beside the failure would invite reading it as data.
+    let ladder = null, linksOut = null;
+    if (rec.ok) {
+      try { ladder = consoleState.ladder({ root, id }); }
+      catch (e) { ladder = { ok: false, error: 'the ladder could not be derived: ' + String((e && e.message) || 'error').slice(0, 140) }; }
+      // An ABSENT record declares nothing, so there is nothing for the handoff reader to read —
+      // distinct from a record that declares no handoff, which readLinks reports as empty.
+      if (!rec.absent) {
+        try { linksOut = handoff.readLinks(rec.frontmatter || {}); }
+        catch (e) { linksOut = null; void e; }
+      }
+    }
+    let index = { initiatives: [] };
+    try { if (wsShape(root) === 'pmos') index = initiativeIndex(root); }
+    catch (e) { void e; }
+    const stateDir = fourPanel.storeDir(engine.engine, root);
+    const out = fourPanel.assemble({
+      id, rec, ladder, links: linksOut, index,
+      sessions: sessionList(), workspaces: wsList(),
+      anchor: rec.ok && !rec.absent
+        ? fourPanel.anchorFor({ anchors: anchorLib(), root, raw: (rec.frontmatter || {}).parent_kr })
+        : null,
+      artifactLinks: fourPanel.readDeclarations(stateDir, fourPanel.ARTIFACT_LINKS),
+      initiativeLinks: fourPanel.readDeclarations(stateDir, fourPanel.INITIATIVE_LINKS),
+    });
+    // Discriminated READ results stay 200 — the body carries the reason, the transport code cannot.
+    return json(res, { ws: w ? w.id : null, ...out });
+  }
+  if (p === '/api/initiative/link' && req.method === 'POST') {
+    // Recording that an artifact corresponds to an external page. This writes a DECLARATION and
+    // makes no request: PMOS holds no credential, so it can state what the PM says the mapping is
+    // and it cannot state anything about the destination's contents.
+    const w = getWs(url.searchParams.get('ws'));
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w2 = body.ws ? getWs(body.ws) : w;
+    const kind = String(body.store || 'artifact');
+    const built = kind === 'initiative'
+      ? fourPanel.initiativeLinkRow(body)
+      : fourPanel.artifactLinkRow(body);
+    if (!built.ok) return json(res, { ok: false, error: built.error }, 400);
+    const engine = consoleState.loadEngine();
+    if (!engine.ok) return json(res, { ok: false, error: engine.error }, 500);
+    const stateDir = fourPanel.storeDir(engine.engine, w2 ? w2.root : SELF_ROOT);
+    const wrote = fourPanel.appendDeclaration(
+      stateDir,
+      kind === 'initiative' ? fourPanel.INITIATIVE_LINKS : fourPanel.ARTIFACT_LINKS,
+      built.row,
+    );
+    // A write that failed returns 500 and says so — never a false green (the /api/gate rule).
+    return json(res, { ...wrote, connectors: fourPanel.connectors() }, wrote.ok ? 200 : 500);
   }
   if (p === '/api/search') {
     // Episodic recall over this workspace's own past sessions. Localhost only, like everything
@@ -2811,15 +3838,25 @@ wss.on('connection', (ws) => {
     } else if (m.t === 'resize') {
       const s = sessions.get(m.id); if (s && s.pty) { try { s.pty.resize(m.cols, m.rows); s.cols = m.cols; s.rows = m.rows; } catch {} }
     } else if (m.t === 'new') {
-      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate });
-      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: 'branch: ' + r.error })); return; }
+      const r = spawnWithBranch({ name: m.name, agent: m.agent, cwd: m.cwd, ws: m.ws, branch: m.branch, createBranch: m.createBranch, isolate: m.isolate, profile: m.profile });
+      // A refused profile is its own sentence, not "branch: …" — the composer's error line names
+      // what PMOS could not read, and nothing was started.
+      if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^profile /.test(r.error || '') ? '' : 'branch: ') + r.error })); return; }
       // a non-fatal truth about what just happened (a worktree's path, a branch ignored on a
       // non-repo) — said out loud, never swallowed
       if (r.notice) ws.send(JSON.stringify({ t: 'notice', notice: r.notice }));
       ws.send(JSON.stringify({ t: 'created', id: r.session.id }));
     } else if (m.t === 'respawn') {
       const old = sessions.get(m.id); if (!old || old.pty) return;
-      const s = spawnSession({ name: old.name, agent: old.agent, cwd: path.relative(old.root, old.cwd), ws: old.ws });
+      // `respawn` is UNCHANGED on the wire (profiles R9): the profile is read off the record the
+      // server already holds, not re-sent by the client — a client that forgot it would otherwise
+      // silently restart the pane on a different environment, and the pane would look identical.
+      const carried = 'profile' in old ? old.profile : null;
+      const s = spawnSession({ name: old.name, agent: old.agent, cwd: path.relative(old.root, old.cwd), ws: old.ws, profile: carried });
+      // A descriptor deleted since the original spawn does NOT get substituted. The respawn goes
+      // ahead with no profile — the pane line already says so — and the reason is said out loud
+      // rather than left for the PM to notice.
+      if (s.profileRefusal) ws.send(JSON.stringify({ t: 'notice', notice: `respawned without a profile — ${s.profileRefusal}` }));
       removeSession(old.id);   // the corpse doesn't linger — respawn replaces, not accumulates
       ws.send(JSON.stringify({ t: 'created', id: s.id }));
     } else if (m.t === 'kill') {
@@ -2915,4 +3952,8 @@ module.exports = { server, spawnSession, removeSession, renameSession, sessions,
   trimBuf, SCROLLBACK,
   // the liveness heartbeat's guard, exported pure so the "idle machine stays idle" half can be
   // asserted without a server that has no clients (the suite always has both).
-  shouldHeartbeat, LIVENESS_MS, TX_REREAD_MS };
+  shouldHeartbeat, LIVENESS_MS, TX_REREAD_MS,
+  // where the anchor resolver is looked for — exported so the suite can assert the INSTALL
+  // location is in the list. A dev checkout satisfies entry 1 and would hide the loss of entry 2
+  // exactly as it hid the workflow engine's absence for four releases (PKG4).
+  ANCHOR_LIB_PATHS };