create-pmos 0.52.0 → 0.53.0

package/workspace/server.js

@@ -124,6 +124,13 @@ const profilesLib = require('./lib/profiles');         // readProfiles(homeDir)
 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
+const planItems = require('./lib/plan-items.js');      // pm-os-absorb Run 1 — the ONE writer and fold of plan-items.jsonl (control graph)
+const planTree = require('./lib/plan-tree.js');        // …and the Breakdown layout: derived stages, owed rows, the Board columns
+const routeModules = require('./lib/route-modules.js'); // pm-os-absorb Runs 2–5 — each run's routes in its own lib/routes-<name>.js
+const needsProviders = require('./lib/needs-providers.js'); // …and each run's needs-you rows, folded into deriveNeeds
+const pmGuard = require('./lib/pm-guard.js');          // pm-os-absorb Run 2 (R25) — Origin, nonce and writer fields on every PM press
+const actorLib = require('./lib/actor.js');            // …the session-token hash persisted with each agent session
+const grantMint = require('./lib/grant-mint.js');      // …one D81 grant for a bulk lifecycle press (501 until 2B fills it)
 // 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
@@ -279,9 +286,12 @@ const SHELL = defaultShell();
 // "child session" marker and disables its own transcript saving. Strip those markers here: the
 // harness inside the PTY must run as though the PM launched it directly. Login/subscription do
 // NOT live in these vars (they're in the CLI's own config/keychain), so this never affects auth.
+// PMOS_SESSION and PMOS_BIN are the same kind of marker (pm-os-absorb Run 1): a server started from inside an agent
+// session holds that session's token, and a shell that inherited it would record the PM's `pmos item` as the agent's.
+// spawnSession gives them to an agent session only, as its own values.
 const INHERITED_SESSION_MARKERS = [
   'CLAUDECODE', 'CLAUDE_CODE_CHILD_SESSION', 'CLAUDE_CODE_SESSION_ID', 'CLAUDE_CODE_ENTRYPOINT',
-  'CLAUDE_CODE_EXECPATH', 'CLAUDE_PID', 'AI_AGENT', 'CLAUDE_EFFORT',
+  'CLAUDE_CODE_EXECPATH', 'CLAUDE_PID', 'AI_AGENT', 'CLAUDE_EFFORT', 'PMOS_SESSION', 'PMOS_BIN',
 ];
 function sessionEnv() {
   const env = { ...process.env };
@@ -1847,7 +1857,7 @@ function surfaceInitiatives(root, w) {
   const acc = readAcceptances(w);
   const life = readLifecycle(w);
   const runs = readRunCounts(w);
-  const needsRaw = readNeeds(w) || [];
+  const needsRaw = (readNeeds(w) || []).filter(notPlanNeed);
   const needsBy = new Map();
   for (const n of needsRaw) if (n && n.initiative_id) needsBy.set(n.initiative_id, (needsBy.get(n.initiative_id) || 0) + 1);
 
@@ -2189,6 +2199,11 @@ const SEED_SETS = {
     { name: 'Bi-weekly report draft', skill: 'report-biweekly', cadence: 'bi-weekly', day: 'Fri', time: '16:00' },
     { name: 'Monthly report draft', skill: 'report-monthly', cadence: 'monthly', dayOfMonth: 1, time: '08:00' },
   ],
+  // Run 5 (X19): the agent step that brings tracker-owned plan items up to date from local files. It is its own set, not a
+  // fifth line of `reports`, so pressing `reports` still makes the four report schedules. It is weekly, Friday 15:30: the
+  // bi-weekly draft (Friday 16:00) fires every other week from whichever Friday it was set up, and a weekly refresh is
+  // never out of step with it. A refresh that finds no change writes no line.
+  tracker: [{ name: 'Tracker refresh', skill: 'tracker-refresh', cadence: 'weekly', day: 'Fri', time: '15:30' }],
 };
 function readSchedules() {
   try { const a = JSON.parse(fs.readFileSync(schedFile(), 'utf8')); return Array.isArray(a) ? a : []; } catch { return []; }
@@ -2336,6 +2351,12 @@ 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 breakdown item a Hand to agent session is bound to, so a restart keeps the binding (pm-os-absorb Run 1).
+  if (s.plan_item) meta.plan_item = s.plan_item;
+  // pm-os-absorb Run 2 (R25): the SHA-256 of the agent's PMOS_SESSION token, never the token (D08). A restored session
+  // has no token in memory, so its stored hash is written back; lib/actor.js sessionForToken reads the map after a restart.
+  const th = s.token ? actorLib.tokenHash(s.token) : (typeof s.tokenHash === 'string' ? s.tokenHash : null);
+  if (th) meta.tokenHash = th;
   // 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
@@ -2604,6 +2625,8 @@ function sessionList() {
       id: s.id, ws: s.ws, name: s.name, agent: s.agent, state: s.state, created: s.created,
       model: 'model' in s ? s.model : null, model_line: modelLib.line('model' in s ? s.model : null),
       cwd: path.relative(s.root, s.cwd) || '.', note: s.note || '', origin: s.origin || null,
+      plan_item: s.plan_item || null,   // Hand to agent: the breakdown item this session is bound to (pm-os-absorb Run 1)
+      // No `token` and no `tokenHash` here, ever: the page never sees a session token (F5; r25-guards.test.js checks it).
       // Derived presentation state, JOINED from both sources: the cadence clock above and the
       // transcript's answer to whose turn it is (lib/session-state). working | quiet | exited |
       // needs | blocked. `shell`-ness stays on `agent`, because it is orthogonal to state;
@@ -2836,10 +2859,12 @@ function tmuxKillSession(name) { if (TMUX && name) tmuxCtl(['kill-session', '-t'
 // 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) {
+// `extra` carries what PMOS itself gives one session (PMOS_SESSION, its token for `pmos item`); the profile
+// overlay stays LAST so nothing in `extra` can unset the workspace flag the overlay carries.
+function createTmuxSession(name, cmd, workdir, cols, rows, extra, overlay) {
   if (tmuxHasSession(name)) return false;
   const eArgs = [];
-  for (const [k, v] of Object.entries(overlay || {})) eArgs.push('-e', `${k}=${v}`);
+  for (const [k, v] of Object.entries({ ...(extra || {}), ...(overlay || {}) })) eArgs.push('-e', `${k}=${v}`);
   const r = tmuxCtl(['-f', TMUX_CONF, 'new-session', '-d', '-s', name,
     ...eArgs, '-x', String(cols || 80), '-y', String(rows || 24), '-c', workdir, '--', cmd]);
   return r.status === 0;
@@ -3049,8 +3074,16 @@ function resolveProfileForSpawn(id) {
       : `profile "${id}" is not among the descriptors in ${read.dir} — PMOS will not substitute another` };
 }
 
-function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, initiative, modelAsk }) {
+function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, initiative, modelAsk, planItem }) {
   const id = nextSessionId();
+  /* pm-os-absorb Run 1 — every AGENT session gets a token, `<id>.<8 hex>`, in its environment as PMOS_SESSION, and
+   * PMOS_BIN, this workspace's own bin/pmos.js. `pmos item` run inside it is then attributed `agent:<token>` (the token
+   * wins over a terminal, lib/plan-items.js actorFromCli). A plain shell session is the PM's own terminal, so it gets
+   * neither (both set empty, never the server's own), and its `pmos item` stays the PM's. The token is an attribution,
+   * not a secret, and Run 2's nonce is the guard. The ledger keeps it whole (it is committed with the repository); the
+   * routes the page reads send `agent:sess-<n>` without it (lib/plan-items.js layoutForPage and needsFor), and the
+   * session list does not carry it. */
+  const sessionToken = `${id}.${crypto.randomBytes(4).toString('hex')}`;
   const w = getWs(ws);
   const root = w ? w.root : SELF_ROOT;
   const isShell = agent === 'shell';
@@ -3071,8 +3104,17 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
   // `profileRefusal` is server-internal: callers that can refuse read it and say why.
   const pres = resolveProfileForSpawn(profile);
   const penv = sessionEnvWithProfile(pres.profile);
+  // sessionEnvWithProfile returns a fresh object (sessionEnv copies process.env), so these touch this session only.
+  // sessionEnv() already strips both from the server's own environment. A shell still gets them SET EMPTY: on tmux they
+  // travel as `-e`, which overrides a daemon an older server seeded with its token, and an empty PMOS_SESSION fails
+  // SESSION_RE, so a `pmos item` typed in the shell is the PM's.
+  const itemEnv = isShell ? { PMOS_SESSION: '', PMOS_BIN: '' } : { PMOS_SESSION: sessionToken, PMOS_BIN: path.join(__dirname, 'bin', 'pmos.js') };
+  Object.assign(penv, itemEnv);
   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 };
+  // Hand to agent: the breakdown item this session was started for, or null. Set only by /api/plan-items/handoff/go.
+  base.plan_item = planItem || null;
+  base.token = sessionToken;
 
   /* WHICH MODEL (D75). Resolved once, here, with the profile, so the record can say only what was applied.
    * Three states are kept apart — not asked, applied, and "this binary has no model control" — and a choice that
@@ -3127,7 +3169,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
     // 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.
     // The launch args are plain tokens by construction (pmos-model's strict pattern), so joining them is safe.
-    if (!createTmuxSession(tname, launchArgs.length ? [cmd, ...launchArgs].join(' ') : cmd, workdir, 80, 24, sessionFlag.tmuxOverlay(profileOverlay(pres.profile)))) {
+    if (!createTmuxSession(tname, launchArgs.length ? [cmd, ...launchArgs].join(' ') : cmd, workdir, 80, 24, itemEnv, sessionFlag.tmuxOverlay(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`;
@@ -3191,7 +3233,7 @@ function spawnSession({ name, agent, cwd, ws, origin, initialInput, profile, ini
 // 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, profile, initiative, modelAsk, origin, initialInput }) {
+function spawnWithBranch({ name, agent, cwd, ws, branch, createBranch, isolate, profile, initiative, modelAsk, origin, initialInput, planItem }) {
   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
@@ -3238,7 +3280,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, profile: pres.id, initiative, modelAsk, origin, initialInput });
+  const s = spawnSession({ name, agent: agent || 'shell', cwd, ws: targetWs, profile: pres.id, initiative, modelAsk, origin, initialInput, planItem });
   // The co-tenancy fact, on the ordinary path too. Note where this sits: OUTSIDE the `if (branch)`
   // block above. The isolate default already computes that other sessions would be disturbed — and
   // then the whole git block is skipped when no branch was picked, which is the common path and the
@@ -3341,7 +3383,7 @@ function startPreview({ initiative, repoKey, ws }) {
 // One click. Resolves the policy, then hands the SAME seam spawnWithBranch already exposes the
 // branch/isolate decision it made — so the inherited hard floor (a failed git operation spawns
 // nothing) is enforced in exactly one place and is not re-implemented here.
-function startWork({ initiative, repoKey, ws, agent, name, profile, origin, initialInput }) {
+function startWork({ initiative, repoKey, ws, agent, name, profile, origin, initialInput, planItem }) {
   const key = repoKeyFor({ repoKey, ws });
   if (!key) return { ok: false, error: 'no repository selected' };
   const trees = treesOfRepo(key);
@@ -3367,6 +3409,8 @@ function startWork({ initiative, repoKey, ws, agent, name, profile, origin, init
     // next-step-actions: a session started from a next step carries its origin (so the budget can count it) and its
     // prompt. Only the /api/next-step/go route passes either; the socket's `start` message never does.
     origin, initialInput,
+    // Hand to agent (pm-os-absorb Run 1): only /api/plan-items/handoff/go passes it.
+    planItem,
   });
   if (!r.ok) return r;
   return { ok: true, session: r.session, notice: r.notice || plan.why, plan: plan.plan };
@@ -3434,7 +3478,7 @@ function nextStepsFor(w, id) {
   const acc = readAcceptances(w).get(id) || {};
   const lc = readLifecycle(w).get(id) || null;
   const ns = deriveNextSteps({ id, accepted: acc.action === 'accept', returned: acc.action === 'return',
-    lifecycle: lc && lc.state !== 'active' ? lc : null, ladder, needs: (readNeeds(w) || []).filter((n) => n && n.initiative_id === id),
+    lifecycle: lc && lc.state !== 'active' ? lc : null, ladder, needs: (readNeeds(w) || []).filter((n) => n && n.initiative_id === id && notPlanNeed(n)),
     sessions: sessRows.filter((x) => x.initiative === id || liveIds.has(x.id)) });
   nextStepActions.annotate(ns, (it) => nextStepPathOf(root, it));
   attachRuns(ns, id);
@@ -3469,6 +3513,55 @@ function prepareNextStep(body) {
     judgment: { on: judgmentOn, outside_service: judgmentOn, needs_key: judgmentOn, note: judgmentOn ? 'The question text leaves this machine for the Typesafe service. It needs TYPESAFE_API_KEY in the session.' : 'No outside service is used.' } };
 }
 
+// ── Hand to agent (pm-os-absorb Run 1, PRD R14) ────────────────────────────────────────────────────────────────
+// A breakdown item is PREPARED (read-only: the first prompt line, where the session will run, the full prompt folded
+// away) and then STARTED by the PM's press with exactly that prompt — the next-step pattern. The session is bound to
+// the item (`plan_item`) and reports with `pmos item`. Neither step writes plan-items.jsonl or planning/work-items.jsonl:
+// materialization arrives in Run 4. Nothing else starts a bound session — no drag or drop reaches this code.
+const HANDOFF_WHERE = { 'new-worktree': 'new branch', 'reuse-worktree': 'its branch', 'main-tree-on-branch': 'its branch', 'main-tree': 'this tree' };
+// The next-step budget, with Hand to agent sessions counted beside next-step ones: both are sessions the workspace
+// starts on the PM's behalf. nsBudget() itself is unchanged, so the next-step limit reads exactly as before.
+function handoffBudget() {
+  const today = new Date().toDateString();
+  const all = [...sessions.values()];
+  const running = all.filter((x) => (x.origin === 'next-step' || x.origin === 'plan-item') && x.state !== 'exited').length;
+  const startedToday = nsRead(NS_RUNS()).filter((r) => r && r.at && new Date(r.at).toDateString() === today).length
+    + all.filter((x) => x.origin === 'plan-item' && x.created && new Date(x.created).toDateString() === today).length;
+  return sessionBudget.check({ running, startedToday, limits: nsLimits() });
+}
+function prepareHandoff(body) {
+  const w = body && body.ws ? workspaces.get(String(body.ws)) : null;
+  if (!w) return { ok: false, status: 404, error: 'no such workspace' };
+  const itemId = String((body && body.item) || '');
+  if (!planItems.ID_RE.test(itemId)) return { ok: false, status: 400, error: 'item must be an item id, <initiative>.<10 characters>' };
+  let fold;
+  try { fold = planItems.readFold(w.root); }
+  catch (e) { return { ok: false, status: 500, error: 'could not read the plan-items ledger: ' + String((e && e.message) || 'error').slice(0, 140) }; }
+  const it = fold.items[itemId];
+  if (!it) return { ok: false, status: 404, error: `no item ${itemId} in this repository` };
+  const live = [...sessions.values()].find((x) => x.plan_item === itemId && x.state !== 'exited');
+  if (live) return { ok: false, status: 409, error: 'a session is already working on this item', session: live.id };
+  /* Hand to agent starts an AGENT, never a shell: a prompt typed into a shell would run as commands, and an item's note
+   * is text an agent can write. The page never sends `agent`; anything but claude is refused rather than swapped. */
+  if (body.agent != null && body.agent !== 'claude') return { ok: false, status: 400, error: 'Hand to agent starts claude' };
+  const agent = 'claude';
+  let stageLabel = it.stage;
+  try { const st = planTree.stagesFor(w.root, it.initiative).find((x) => x.id === it.stage); if (st) stageLabel = st.label; } catch { /* the id stands in */ }
+  const gone = new Set(fold.withdrawnIds || []);
+  const { first, prompt } = planItems.handoffPrompt({ ...it, after: (it.after || []).filter((x) => !gone.has(x)) }, it.initiative, stageLabel);
+  const preview = startPreview({ initiative: it.initiative, ws: w.id });
+  if (!preview.ok) return { ok: false, status: 409, error: preview.error || 'no branch and tree could be chosen for this item' };
+  const where = HANDOFF_WHERE[preview.plan] || preview.plan;
+  return {
+    ok: true, item: itemId, initiative: it.initiative, agent, plan: preview.plan, where, first,
+    line: `Agent will: ${first} · ${where}`, prompt,
+    // Go starts exactly what was shown: the prompt, the plan, the agent, the branch and the tree it was shown for.
+    prompt_sha: crypto.createHash('sha256').update([prompt, preview.plan, agent, preview.branch || '', preview.wsId || preview.dir || '', w.id].join('\n')).digest('hex'),
+    details: { branch: preview.branch || null, tree: preview.dir || null, session_name: 'item: ' + it.title.slice(0, 40) },
+    ws: w.id,
+  };
+}
+
 // ── Background prepare, slice D3 (initiative proactive-engine) ──────────────────────────────────────────────────
 // The PM approves ONE plan hash from Today. The 60-second tick later starts that session through the SAME path a next-step
 // `go` uses (startWork with origin next-step and the prompt that was shown), only while background prepare is on, outside quiet
@@ -3560,7 +3653,7 @@ function proactiveCtx(now, settings) {
         const lc = life.get(b.id); const stopped = !!(lc && lc.state !== 'active');
         entry.initiatives.push({ id: b.id, title: b.title || b.id, active: !b.accepted && !stopped, lane: b.lane || null, lastRun: lastRun.has(b.id) ? lastRun.get(b.id) : null, hasRuns: hasRuns.has(b.id) });
       }
-      entry.needs = (readNeeds(w) || []).filter((n) => n).map((n) => ({ initiative_id: n.initiative_id || null, question: n.question || '', run_id: n.run_id || null }));
+      entry.needs = (readNeeds(w) || []).filter((n) => n && notPlanNeed(n)).map((n) => ({ initiative_id: n.initiative_id || null, question: n.question || '', run_id: n.run_id || null }));
       for (const [id, a] of acc) if (a && a.action === 'return') entry.returned.push({ initiative_id: id, note: 'returned at the Acceptance Gate', at: a.at });
       entry.schedules = allSchedules.filter((x) => r.ids.has(x.ws)).map((x) => ({ id: x.id, name: x.name || x.label || x.skill || x.id, lastStatus: x.lastStatus || null, lastRun: x.lastRun || null }));
     } catch (e) { entry.error = 'the repository could not be read — ' + String((e && e.message) || 'error').slice(0, 120); }
@@ -3875,10 +3968,33 @@ function leadingFrontmatter(file) { return fmParse.leadingFrontmatter(file); }
 // The outcome rule mirrors kit/scripts/metrics.py EXACTLY, including "a missing horizon counts
 // as due" — a bet with no judgment date can never come due by itself (horizon-gaming-by-omission).
 // Derivation only ever reports; it never disposes anything (D57).
+/* The plan-items ledger belongs to the REPOSITORY (lib/plan-items.js ledgerRoot), not to a working tree, so its needs
+ * rows are derived for ONE registered tree of it: the tree at the ledger's root, else the first registered. Otherwise a
+ * repository with a linked worktree registered would count every Keep card twice. */
+function isPlanNeedsTree(w) {
+  let mine; try { mine = planItems.ledgerRoot(w.root); } catch { return true; }
+  const same = [...workspaces.values()].filter((t) => { try { return planItems.ledgerRoot(t.root) === mine; } catch { return false; } });
+  if (!same.some((t) => t.id === w.id)) return true;
+  const lead = same.find((t) => path.resolve(t.root) === mine) || same[0];
+  return lead.id === w.id;
+}
 function deriveNeeds(w) {
+  if (!w) return [];
+  /* pm-os-absorb Run 1 — the breakdown's needs come FIRST and do not depend on a state directory: one Keep card
+   * per agent batch, an agent Done with no evidence, and a Keep line that was not written from the page. A ledger
+   * that cannot be read is said here, as a row, rather than turned into an empty list or a 500 for every caller. */
+  let needs = [];
+  if (isPlanNeedsTree(w)) {
+    try { needs = planItems.needsFor(w.root).map((n) => ({ ...n, ws: w.id })); }
+    catch (e) {
+      needs = [{ run_id: 'plan-items:unreadable', initiative_id: null, kind: 'plan-flag', derived: true, doc: null, ws: w.id,
+        question: 'The plan-items ledger could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }];
+    }
+  }
+  // pm-os-absorb Runs 2–5 — the planning layer's other needs rows, one provider file per run (lib/needs-providers.js).
+  needs = needs.concat(needsProviders.rowsFor(w, { lead: isPlanNeedsTree(w) }));
   const dir = stateDirFor(w);
-  if (!dir) return [];
-  const needs = [];
+  if (!dir) return needs;
   const settled = new Set();
   for (const a of readLedger(w, 'acceptances.jsonl')) if (a.run_id) settled.add(a.run_id);
   for (const e of readLedger(w, 'evals.jsonl')) {
@@ -3923,6 +4039,13 @@ function readNeeds(w) {
   const seen = new Set(queued.map((n) => n && n.run_id).filter(Boolean));
   return queued.concat(deriveNeeds(w).filter((n) => !seen.has(n.run_id)));
 }
+/* pm-os-absorb Run 1 — the breakdown's needs rows (a Keep card, an agent Done with no evidence, a forged Keep) are the
+ * PM's to act on in needs-you and Today, so /api/needs and the per-tree counts carry them. They are NOT evidence for
+ * an initiative's derived state, its next steps or the portfolio's needs list: those read the rows they read before
+ * Run 1, so a pending Keep does not turn an initiative `blocked` with a sentence naming needs.json, and Today does not
+ * show the same batch twice (once as a Keep card, once as an "Unblock" initiative card). */
+const PLAN_NEED_KINDS = new Set(['keep', 'evidence', 'plan-flag']);
+const notPlanNeed = (n) => !(n && n.derived === true && PLAN_NEED_KINDS.has(n.kind)) && !needsProviders.isProviderRow(n);
 
 // ── Read-only console surfaces over file-mode state (D64 Track B). ──────────────────────
 // The committed hosted snapshot is the seed/demo source when no LIVE file-mode state exists; the
@@ -3959,6 +4082,10 @@ function needsResult(w) {
     run_id: n.run_id || null, kind: n.kind || 'question', initiative_id: n.initiative_id || null,
     question: n.question || n.t || '(unstated)', derived: !!n.derived, doc: n.doc || null,
     deliverable: n.deliverable || null,
+    // pm-os-absorb Run 1 — a breakdown row keeps what its card needs; other rows are unchanged (no new keys).
+    ...(n.ws ? { ws: n.ws } : {}), ...(n.batch ? { batch: n.batch } : {}), ...(n.item ? { item: n.item } : {}), ...(n.flag ? { flag: n.flag } : {}),
+    // pm-os-absorb Runs 2–5 — a provider row's Today card (lib/needs-providers.js); absent on every other row.
+    ...(n.today && typeof n.today === 'object' ? { today: n.today } : {}),
   }));
   // `all` is the RAW combined queue — what readNeeds(w) computes — carried so /api/needs can serve
   // both the strict state and the queue from one derivation instead of deriving twice per request.
@@ -3996,10 +4123,14 @@ const needsAgg = new Map();     // ws id -> { at, sig, value }
 // requirement is about. `none` and `unreadable` are distinct signatures on purpose; a file that
 // appears, vanishes or becomes unstattable each invalidate.
 function needsSig(w) {
+  // The plan-items ledger feeds needs too (Keep, no evidence, forged Keep), so its signature is part of this one.
+  let plan = 'none';
+  try { plan = planItems.ledgerSigs([{ id: w.id, root: w.root }], null)[w.id].items; } catch { plan = 'unreadable'; }
+  plan += '|' + needsProviders.sigFor(w);   // pm-os-absorb Runs 2–5 — and every needs provider's
   const f = needsFileFor(w);
-  if (!f) return 'none';
-  try { const st = fs.statSync(f); return `${st.mtimeMs}:${st.size}`; }
-  catch { return 'unreadable'; }
+  if (!f) return `none|${plan}`;
+  try { const st = fs.statSync(f); return `${st.mtimeMs}:${st.size}|${plan}`; }
+  catch { return `unreadable|${plan}`; }
 }
 function needsCountCached(w) {
   const hit = needsAgg.get(w.id);
@@ -4793,7 +4924,18 @@ async function handleRequest(req, res) {
   const url = new URL(req.url, 'http://localhost');
   const p = url.pathname;
 
-  if (p === '/' || p === '/index.html') return serveFile(res, path.join(PUB, 'index.html'), null, true);
+  if (p === '/' || p === '/index.html') {
+    // pm-os-absorb Run 2 (R25, X11): the per-launch nonce goes into the base meta line, nowhere else. no-store, so a
+    // restarted server never answers a press from a page that holds the previous launch's value.
+    const n = pmGuard.launchNonce();
+    if (!n) return serveFile(res, path.join(PUB, 'index.html'), null, true);
+    return fs.readFile(path.join(PUB, 'index.html'), 'utf8', (err, html) => {
+      if (err) { res.writeHead(404); res.end('not found'); return; }
+      const out = html.replace('<meta name="' + pmGuard.NONCE_META + '" content="" />', '<meta name="' + pmGuard.NONCE_META + '" content="' + n + '" />');
+      res.writeHead(200, { 'Content-Type': TYPES['.html'], 'Cache-Control': 'no-store' });
+      res.end(out);
+    });
+  }
   // 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
@@ -4818,6 +4960,10 @@ 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'));
+  // pm-os-absorb — the words an initiative shows (R3), one mapping for the page and for node over every record.
+  if (p === '/lib/initiative-display.js') return serveFile(res, path.join(__dirname, 'lib', 'initiative-display.js'));
+  // pm-os-absorb — the dated bars of a breakdown (R20): Breakdown › Timeline, Initiatives › Timeline and the report strip.
+  if (p === '/lib/item-spans.js') return serveFile(res, path.join(__dirname, 'lib', 'item-spans.js'));
   // …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
@@ -4846,6 +4992,10 @@ async function handleRequest(req, res) {
   // 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'));
+  // D86 — the two vendored browser libraries of pm-os-absorb Run 1, committed under public/vendor/ (no CDN, no
+  // package.json entry). SortableJS does every drag; the sprite holds the lucide icons the Breakdown uses.
+  if (p === '/vendor/Sortable.min.js') return serveFile(res, path.join(PUB, 'vendor', 'Sortable.min.js'));
+  if (p === '/vendor/lucide-sprite.js') return serveFile(res, path.join(PUB, 'vendor', 'lucide-sprite.js'));
   // ── 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
@@ -5060,6 +5210,9 @@ async function handleRequest(req, res) {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
     catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    // R25: writing parent_kr is the anchor change, a PM-only act.
+    const g = pmGuard.requirePmPress(req, body, { act: 'anchor' });
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
     // 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) {
@@ -5623,7 +5776,11 @@ async function handleRequest(req, res) {
   }
   // `version` lets the launcher notice a server still running OLD code after an upgrade: files on disk
   // advance under a live process, so the UI would otherwise call routes that process never learned.
-  if (p === '/api/sessions') return json(res, { sessions: sessionList(), version: APP_VERSION });
+  // `ledgers` (pm-os-absorb Run 1) — the plan-items signature of every registered workspace, so an open Breakdown
+  // knows to refetch: `items` is one stat per workspace; `evidence` is computed only for the ids in ?ledgers=
+  // (at most 4). Computed on this request and never stored (D33).
+  if (p === '/api/sessions') return json(res, { sessions: sessionList(), version: APP_VERSION,
+    ledgers: planItems.ledgerSigs([...workspaces.values()].map((w) => ({ id: w.id, root: w.root })), url.searchParams.get('ledgers')) });
   if (p === '/api/git/branches') {
     // Read-only branch awareness for a workspace. A non-repo returns {ok:false} (never a fake
     // branch). Fixed git args, no caller input in the read path (R1).
@@ -5788,13 +5945,16 @@ async function handleRequest(req, res) {
   // per-tree counts a COLLAPSED sidebar row shows, which is the whole reason a row can be collapsed.
   if (p === '/api/needs') {
     const w = getWs(url.searchParams.get('ws'));
+    // The signature is taken BEFORE the read, as needsCountCached takes it: a write between the two then leaves an
+    // older signature on the cached count (read again on the next call), never a newer one on an older count.
+    let sig = null;
+    if (w) { try { sig = needsSig(w); } catch { sig = 'unreadable'; } }
     const strict = needsResult(w);
     // One derivation per request, not three: the strict read already holds the combined queue
     // (`all` — identical to readNeeds when the read succeeds; on a corrupt file readNeeds keeps its
     // lenient derived-only fallback), and the by_ws cache is seeded from the same read so the
     // selected tree is not derived again — fresher than any cache hit, so R10 still holds.
     if (w) {
-      let sig; try { sig = needsSig(w); } catch { sig = 'unreadable'; }
       needsAgg.set(w.id, { at: Date.now(), sig, value: strict.ok
         ? { count: strict.empty ? 0 : strict.data.items.length, error: null }
         : { count: null, error: strict.error } });
@@ -5904,7 +6064,7 @@ async function handleRequest(req, res) {
       nextSteps = deriveNextSteps({
         id, accepted: acc.action === 'accept', returned: acc.action === 'return',
         lifecycle: lc && lc.state !== 'active' ? lc : null, ladder,
-        needs: (readNeeds(w) || []).filter((n) => n && n.initiative_id === id),
+        needs: (readNeeds(w) || []).filter((n) => n && n.initiative_id === id && notPlanNeed(n)),
         sessions: sessRows.filter((x) => (x.initiative === id) || conversations.some((c) => c.id === x.id && c.live)),
       });
     } catch (e) { nextSteps = { state: 'unreadable', summary: 'The next steps could not be derived — ' + String((e && e.message) || 'error').slice(0, 120), items: [] }; }
@@ -5984,6 +6144,9 @@ async function handleRequest(req, res) {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
     catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    // R25 / R23: binding decides which initiatives an agent session works on, so an agent cannot bind itself.
+    const g = pmGuard.requirePmPress(req, body, { act: 'bind' });
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
     const s = sessions.get(String(body.id || ''));
     if (!s) return json(res, { ok: false, error: 'no such session' }, 404);
     const clearing = body.initiative === null || body.initiative === '';
@@ -6141,6 +6304,10 @@ async function handleRequest(req, res) {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
     catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    // R25: every action this route records is the PM's — acceptance, review approve and return, document approval,
+    // contract approval and a D60 disposition. One guard before the action is read, so no action escapes it.
+    const g = pmGuard.requirePmPress(req, body, { act: 'accept' });
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
     if (!body.action || !body.run_id) return json(res, { ok: false, error: 'action and run_id are required' }, 400);
     const w = getWs(body.ws);
     const rec = { at: nowISO(), date: nowISO().slice(0, 10),
@@ -6158,7 +6325,7 @@ async function handleRequest(req, res) {
       // it, validated against the same closed set, and simply absent when they do not.
       accepted: body.action === 'accept' ? true : body.action === 'return' ? false : undefined,
       ...(body.pm_label === 'pass' || body.pm_label === 'fail' ? { pm_label: body.pm_label } : {}),
-      note: body.note || '', workspace: w ? w.name : null, root: w ? w.root : null, pm: true };
+      note: body.note || '', workspace: w ? w.name : null, root: w ? w.root : null, pm: true, by: g.actor.by, via: g.actor.via };
     // A malformed label is refused rather than dropped. Silently discarding it would put the row in
     // the unlabeled pile while the PM believed they had labelled it — the same shape as inferring.
     if (body.pm_label !== undefined && body.pm_label !== 'pass' && body.pm_label !== 'fail') {
@@ -6321,6 +6488,69 @@ async function handleRequest(req, res) {
     const wrote = nsAppend(NS_RUNS(), rec, 'next-step run');
     return json(res, { ok: true, session: { id: started.session.id, name: started.session.name }, notice: started.notice || null, plan: r.plan, run: wrote.ok ? rec.id : null, recorded: wrote.ok });
   }
+  /* ── pm-os-absorb Run 1 — an initiative's breakdown (plan-items.jsonl) ──────────────────────────────────────────
+   * GET is the Breakdown layout: derived stages with their owed rows, the items, the Board columns, the Keep batches.
+   * POST writes through the ONE writer as the PM (`pm:wawan`, `via: ui`). Every POST needs an Origin header: the
+   * global guard already refuses a foreign one, and a request with none did not come from the page. Header values
+   * are never logged (D08). `ladder=0` skips the ladder (about 800 ms here) when only the items changed. */
+  if (p === '/api/plan-items' && req.method === 'GET') {
+    const wsParam = url.searchParams.get('ws');
+    const w = wsParam ? workspaces.get(wsParam) : homeWorkspace();
+    if (!w) return json(res, { ok: false, error: 'no such workspace' }, 404);
+    const id = url.searchParams.get('id') || '';
+    if (!planItems.INIT_RE.test(id)) return json(res, { ok: false, error: 'an initiative id is required, and it must be a record name' }, 400);
+    try {
+      if (!planTree.recordPath(w.root, id)) return json(res, { ok: false, error: `no initiative ${id} in this repository` }, 404);
+      const now = Date.now();
+      // The signature is taken before the ledger and the ladder are read (lib/plan-items.js readLayout says why).
+      const { sig, layout: lay } = planItems.readLayout({ id: w.id, root: w.root }, id, { ladder: url.searchParams.get('ladder') !== '0', now });
+      const out = { ok: true, ws: w.id, initiative: id, profile: lay.profile, lane: lay.lane, ladderIncluded: lay.ladderIncluded };
+      if (lay.ladderIncluded) out.ladder = lay.ladder;
+      Object.assign(out, { sig, now: new Date(now).toISOString(), progress: lay.progress, stages: lay.stages, other: lay.other,
+        items: lay.items, board: lay.board, batches: lay.batches, flags: lay.flags, withdrawnCount: lay.withdrawnCount });
+      return json(res, out);
+    } catch (e) {
+      return json(res, { ok: false, error: 'the breakdown could not be read: ' + String((e && e.message) || 'error').slice(0, 160) }, 500);
+    }
+  }
+  if ((p === '/api/plan-items' || p === '/api/plan-items/handoff/prepare' || p === '/api/plan-items/handoff/go') && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    // R25: pm-guard's body, writer-field, Origin and nonce checks. A call that carries a Keep is the PM-only act `keep`.
+    const keeps = p === '/api/plan-items' && body && Array.isArray(body.events) && body.events.some((e) => e && e.ev === 'kept');
+    const g = keeps ? pmGuard.requirePmPress(req, body, { act: 'keep' }) : pmGuard.requirePagePress(req, body);
+    if (!g.ok) return json(res, { ok: false, error: g.error, ...(p === '/api/plan-items' ? { index: null } : {}) }, g.status);
+    if (p === '/api/plan-items') {
+      const w = body.ws ? workspaces.get(String(body.ws)) : null;
+      if (!w) return json(res, { ok: false, error: 'no such workspace', index: null }, 404);
+      let r;
+      try { r = planItems.appendFromUi(w.root, body.events, { actor: g.actor }); }
+      catch (e) { warnWriteFail('plan-items.jsonl', e); return json(res, { ok: false, error: 'could not record — nothing was saved', index: null }, 500); }
+      if (!r.ok) return json(res, { ok: false, error: r.error, index: r.index }, r.status || 400);
+      invalidateNeedsAgg();   // the ledger is per repository: every tree of it may show a new Keep card
+      const sig = planItems.ledgerSigs([{ id: w.id, root: w.root }], null)[w.id];
+      return json(res, { ok: true, written: r.written, sig });
+    }
+    if (p === '/api/plan-items/handoff/prepare') {
+      const r = prepareHandoff(body);
+      if (!r.ok) { const { status, ...rest } = r; return json(res, rest, status || 400); }
+      const { ws: _ws, ...shown } = r;
+      return json(res, shown);
+    }
+    // go: only the PM's press reaches it. It prepares again and starts one session only when the PM confirmed AND the
+    // prompt and destination are the ones they were shown (the sha). It writes no ledger line.
+    if (body.confirm !== true) return json(res, { ok: false, error: 'confirm is required: this starts a session' }, 400);
+    const r = prepareHandoff(body);
+    if (!r.ok) { const { status, ...rest } = r; return json(res, rest, status || 400); }
+    if (!body.prompt_sha || body.prompt_sha !== r.prompt_sha) return json(res, { ok: false, error: 'the item changed since you reviewed it — prepare it again', prompt_sha: r.prompt_sha }, 409);
+    const budget = handoffBudget();
+    if (!budget.allowed) return json(res, { ok: false, error: budget.reason, budget }, 409);
+    const started = startWork({ initiative: r.initiative, ws: r.ws, agent: r.agent, name: r.details.session_name,
+      origin: 'plan-item', initialInput: r.prompt + '\r', planItem: r.item });
+    if (!started.ok) return json(res, { ok: false, error: started.error }, 409);
+    // The session's token is never projected; the page gets where it runs and the item it is bound to.
+    return json(res, { ok: true, session: { id: started.session.id, name: started.session.name, ws: started.session.ws, plan_item: started.session.plan_item || null },
+      notice: started.notice || null, plan: started.plan });
+  }
   if (p === '/api/next-step/summary' && req.method === 'GET') {
     // What an ended (or running) next-step session did: the files git shows on its branch against trunk, the end of the
     // conversation, and every JUDGMENT line checked against its shape. Read-only.
@@ -6352,6 +6582,8 @@ async function handleRequest(req, res) {
     // The PM's verdict on one step's run. It accepts or sends back THE STEP. It never records an acceptance of the
     // initiative, never changes a status and never touches a lifecycle line.
     let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const g = pmGuard.requirePmPress(req, body, { act: 'accept' });   // R25: accepting or returning a step is the PM's
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
     const verdict = body.verdict === 'accept' ? 'accept' : body.verdict === 'send-back' ? 'send-back' : null;
     if (!verdict) return json(res, { ok: false, error: 'verdict must be accept or send-back' }, 400);
     const note = String(body.note || '').trim().slice(0, 500);
@@ -6361,7 +6593,7 @@ async function handleRequest(req, res) {
     if (!run) return json(res, { ok: false, error: 'that session was not started from a next step' }, 404);
     const live = sessions.get(sid);
     if (live && live.state !== 'exited') return json(res, { ok: false, error: 'the session is still running — review it when it has ended' }, 409);
-    const rec = { at: nowISO(), initiative_id: run.initiative_id, item_id: run.item_id, key: run.key, session_id: sid, verdict, note, pm: 'wawan' };
+    const rec = { at: nowISO(), initiative_id: run.initiative_id, item_id: run.item_id, key: run.key, session_id: sid, verdict, note, pm: 'wawan', by: g.actor.by, via: g.actor.via };
     const wrote = nsAppend(NS_REVIEWS(), rec, 'step review');
     if (!wrote.ok) return json(res, { ok: false, error: wrote.error }, 500);
     return json(res, { ok: true, recorded: rec });
@@ -6828,17 +7060,37 @@ async function handleRequest(req, res) {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
     catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
-    const id = String(body.initiative_id || '');
-    if (!/^[a-z0-9][a-z0-9._-]*$/i.test(id)) return json(res, { ok: false, error: 'initiative_id is required' }, 400);
+    const g = pmGuard.requirePmPress(req, body, { act: 'lifecycle' });   // R25: a lifecycle change is the PM's
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
+    const ID_OK = (v) => typeof v === 'string' && /^[a-z0-9][a-z0-9._-]*$/i.test(v);
+    // The bulk body `{ ws, ids, state }` (D86 point 2, X6): at most 20 ids and one state, under ONE lifecycle-bulk grant.
+    const bulk = body.ids !== undefined;
+    if (bulk && body.initiative_id !== undefined) return json(res, { ok: false, error: 'send initiative_id or ids, not both' }, 400);
+    const ids = bulk ? body.ids : [String(body.initiative_id || '')];
+    if (bulk && (!Array.isArray(ids) || !ids.length || ids.length > 20 || !ids.every(ID_OK) || new Set(ids).size !== ids.length)) {
+      return json(res, { ok: false, error: 'ids must name 1 to 20 different initiatives' }, 400);
+    }
+    const id = ids[0];
+    if (!ID_OK(id)) return json(res, { ok: false, error: 'initiative_id is required' }, 400);
     if (body.state !== 'active' && !STOPPED_STATES.includes(body.state)) {
       return json(res, { ok: false, error: `state must be one of ${STOPPED_STATES.concat('active').join(', ')}` }, 400);
     }
     const w = getWs(body.ws);
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
-    if (!initiativeIndex(w.root).initiatives.some((g) => g.id === id)) {
-      return json(res, { ok: false, error: `no initiative '${id}' in ${w.name}` }, 404);
+    const known = new Set(initiativeIndex(w.root).initiatives.map((x) => x.id));
+    const missing = ids.find((x) => !known.has(x));
+    if (missing) return json(res, { ok: false, error: `no initiative '${missing}' in ${w.name}` }, 404);
+    const reason = String(body.reason || '').slice(0, 500);
+    let grant = null;
+    if (bulk) {
+      const m = grantMint.mintFromPress(w.root, { scope: 'lifecycle-bulk', ids, state: body.state,
+        instruction: `set ${ids.length} initiatives to ${body.state}`, initiative: null }, { actor: g.actor });
+      if (!m.ok) return json(res, { ok: false, error: m.error }, m.status || 500);   // the writer refused or is missing: nothing is written
+      grant = m.grant_id;
     }
-    const rec = { initiative_id: id, state: body.state, reason: String(body.reason || '').slice(0, 500), pm: 'wawan', at: nowISO() };
+    const at = nowISO();
+    const recs = ids.map((x) => ({ initiative_id: x, state: body.state, reason, pm: 'wawan', by: g.actor.by, via: g.actor.via, at, ...(grant ? { grant } : {}) }));
+    const rec = recs[0];
     // The ledger the ENGINE reads for this repository's layout (scripts/workflow-state.js#layout): a repository
     // with planning/initiatives/ keeps its ledgers in planning/runs/, a kit in pmos/state/. Writing anywhere else
     // (R6 wrote the workspace's runtime state for PMOS-self) shows on the board but never clears the gate.
@@ -6849,13 +7101,18 @@ async function handleRequest(req, res) {
     if (!d) return json(res, { ok: false, error: 'this repository has no state directory to record in — nothing was written' }, 500);
     try { fs.mkdirSync(d, { recursive: true }); } catch { /* the guard reports it */ }
     const sink = path.join(d, 'lifecycle.jsonl');
-    try { createSinkGuard({ sink, what: 'lifecycle' }).appendLine(sink, rec); }
+    let wrote = 0;
+    try { const sg = createSinkGuard({ sink, what: 'lifecycle' }); for (const r of recs) { sg.appendLine(sink, r); wrote++; } }
     catch (e) {
       warnWriteFail('lifecycle.jsonl', e);
-      return json(res, { ok: false, error: 'could not record the change — nothing was saved', sink }, 500);
+      // A partial bulk write names the grant that was used and the ids still to set, so the PM can press again for them.
+      const rest = ids.slice(wrote);
+      return json(res, { ok: false, error: wrote
+        ? `could not record the change — ${wrote} of ${recs.length} lines were saved${grant ? ` under grant ${grant}` : ''}; not saved: ${rest.join(', ')}. Set those again.`
+        : 'could not record the change — nothing was saved', sink, ...(wrote ? { grant, unsaved: rest } : {}) }, 500);
     }
     boardCache.invalidate(w.root);
-    return json(res, { ok: true, recorded: rec, sink });
+    return json(res, bulk ? { ok: true, recorded: recs, grant, sink } : { ok: true, recorded: rec, sink });
   }
   if (p === '/api/doc/save' && req.method === 'POST') {
     // The editor's save (workspace-doc-editor R3/R4). The ONLY write path on this surface, and it is
@@ -6865,6 +7122,9 @@ async function handleRequest(req, res) {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
     catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    // R25: a save can rewrite a record's parent_kr, so every save passes the anchor guard. `pm` is a writer field now.
+    const g = pmGuard.requirePmPress(req, body, { act: 'anchor' });
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
 
     const w = getWs(body.ws);
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
@@ -6902,7 +7162,7 @@ async function handleRequest(req, res) {
     // needs.json and acceptances.jsonl use — a tenant product repo has no workspace/ folder, and
     // assuming one is exactly the defect shipped in 0.7.1/0.7.2.
     const region = applyChange.changedRegion(body.base, body.text);
-    const rec = { file: String(body.path), at: nowISO(), pm: body.pm || 'wawan',
+    const rec = { file: String(body.path), at: nowISO(), pm: g.actor.by.slice('pm:'.length), via: g.actor.via,
       note: typeof body.note === 'string' && body.note.trim() ? body.note.trim().slice(0, 400) : null,
       at_line: region.at_line, added: region.added, removed: region.removed,
       before: region.before, after: region.after };
@@ -7067,6 +7327,8 @@ async function handleRequest(req, res) {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
     catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const g = pmGuard.requirePmPress(req, body, { act: 'anchor' });   // R25: an aligning edit can rewrite parent_kr too
+    if (!g.ok) return json(res, { ok: false, error: g.error }, g.status);
     const w = getWs(body.ws);
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 404);
     const rel = String(body.file || '');
@@ -7087,7 +7349,7 @@ async function handleRequest(req, res) {
     const region = applyChange.changedRegion(body.before, body.after);
     const dir = stateDirFor(w, { create: true });
     if (dir) {
-      const rec = { file: rel, at: nowISO(), pm: body.pm || 'wawan',
+      const rec = { file: rel, at: nowISO(), pm: g.actor.by.slice('pm:'.length), via: g.actor.via,
         note: 'aligned with ' + (body.source || 'an earlier change') + (body.why ? ' — ' + String(body.why).slice(0, 200) : ''),
         at_line: region.at_line, added: region.added, removed: region.removed,
         before: region.before, after: region.after, aligned_from: body.source || null };
@@ -7114,6 +7376,8 @@ async function handleRequest(req, res) {
     if (only) rows = rows.filter((r) => r.file === only);
     return json(res, { ok: true, changes: rows.slice(-200).reverse(), total: rows.length });
   }
+  // pm-os-absorb Runs 2–5 — the planning layer's routes, one file per run (lib/route-modules.js). Last, so none shadows a route above.
+  if (await routeModules.dispatch(req, res, url, { json, readBody, getWs, invalidateNeedsAgg, boardCache, consoleState, stateDirFor, sessionList })) return;
   res.writeHead(404); res.end('not found');
 }
 
@@ -7239,7 +7503,16 @@ function handleUpgrade(req, socket, head) {
     socket.destroy();     // reject the upgrade; nothing about the request is logged (D08)
     return;
   }
-  wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+  // R25 (bind): a session started with an initiative is bound to it, a PM-only act. Only a socket the page opened with
+  // this launch's nonce (`?pmos-nonce=`) may bind; any other socket still spawns, unbound, and is told why.
+  const bind = pmGuard.requirePmUpgrade(req, { act: 'bind' });
+  wss.handleUpgrade(req, socket, head, (ws) => { ws._bind = bind; wss.emit('connection', ws, req); });
+}
+/** The initiative a WS spawn may bind, or null with a notice sent when this socket may not bind (R25). */
+function wsBindable(ws, initiative) {
+  if (initiative == null || initiative === '' || (ws._bind && ws._bind.ok)) return initiative;
+  ws.send(JSON.stringify({ t: 'notice', notice: `the session starts without an initiative: ${(ws._bind && ws._bind.error) || 'only the PM can bind a session to an initiative, from the page'}` }));
+  return null;
 }
 server.on('upgrade', handleUpgrade);
 wss.on('connection', (ws) => {
@@ -7278,7 +7551,7 @@ wss.on('connection', (ws) => {
       // `initiative` is what the client has always held and never sent: `＋ session` is clicked on
       // an initiative row, the tab carries its `slug`, and the spawn message named three other
       // fields. An absent or unusable value leaves the session unattributed — never a refused spawn.
-      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, initiative: m.initiative,
+      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, initiative: wsBindable(ws, m.initiative),
         // D75 — what the composer chose (a tier, or a model), carried like the profile. Absent = not asked.
         modelAsk: (m.tier || m.model) ? { explicit: { tier: m.tier, model: m.model, effort: m.effort } } : null });
       // A refused profile is its own sentence, not "branch: …" — the composer's error line names
@@ -7292,7 +7565,7 @@ wss.on('connection', (ws) => {
       // repo-first R1 — the one-click path. It carries an INITIATIVE (or none) and a repository,
       // never a branch and never an isolate flag: those are the policy's to decide, and a client
       // that could still send them would be a second place the rule lives.
-      const r = startWork({ initiative: m.initiative, repoKey: m.repoKey, ws: m.ws,
+      const r = startWork({ initiative: wsBindable(ws, m.initiative), repoKey: m.repoKey, ws: m.ws,
         agent: m.agent, name: m.name, profile: m.profile });
       if (!r.ok) { ws.send(JSON.stringify({ t: 'error', error: (/^profile /.test(r.error || '') ? '' : 'start: ') + r.error })); return; }
       if (r.notice) ws.send(JSON.stringify({ t: 'notice', notice: r.notice }));
@@ -7303,7 +7576,7 @@ wss.on('connection', (ws) => {
       // 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, modelAsk: old.modelAsk || null });
+      const s = spawnSession({ name: old.name, agent: old.agent, cwd: path.relative(old.root, old.cwd), ws: old.ws, profile: carried, modelAsk: old.modelAsk || null, planItem: old.plan_item || null });
       // 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.
@@ -7343,6 +7616,9 @@ if ((HOME_ENABLED || workspaces.size) && [...sessions.values()].filter((s) => s.
 }
 
 if (require.main === module) {
+  // pm-os-absorb Run 2 (R25, X11): one nonce per launch, held in memory only. Never in process.env (so no PTY inherits
+  // it), never logged (D08). GET / templates it into the page; lib/pm-guard.js refuses a press without it.
+  pmGuard.setLaunchNonce(crypto.randomBytes(24).toString('base64url'));
   // Refuse-to-start is the D62 spine: if the requested remote bind isn't loopback or a tailnet
   // address, resolveBinds returned {refused} and we exit rather than expose a PTY server publicly.
   if (BIND.refused) { console.error('✗ ' + BIND.refused); process.exit(1); }