create-pmos 0.41.0 → 0.43.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@ddb2c06
-assembled: 2026-10-03
+kernel-source: pmos@e4f29fe
+assembled: 2026-10-04
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-03T21:04:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T02:41:17Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-03T21:04:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T02:41:17Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-03T21:04:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T02:41:17Z"}
 status: stable
 ---
 

package/payload/state/log.md

@@ -2,6 +2,6 @@
 
 Newest first, ISO dates.
 
-## 2026-10-03
+## 2026-10-04
 
 - Adopted OKF v0.2 (D73).

package/workspace/README.md

@@ -82,6 +82,14 @@ After the session ends, `GET /api/next-step/summary` returns the files the branc
 
 The top of Today is a brief: a greeting, the day's calendar, ranked priorities and a worth-asking list. The server does not build it. The built-in skill `skills/morning-brief.skill` runs in an agent session, reads the sources the settings allow (calendar, wispr, mail, jira, confluence; mail is off by default) and the derived list (`pmos proactive today`), and submits one brief with `pmos proactive brief submit --file`. `POST /api/proactive/brief` checks it with `lib/brief.js` and stores `briefs/<date>.json` in the runtime state folder, replacing any earlier brief for the same day; `GET` returns the newest one with a `stale` flag when its date is not today. The check refuses, with the reason and without storing, a wrong shape, an unknown source, a confidence outside 0 to 1, more than 12 items or 20 events, an over-long field, an item that rests on a source not reported as read, a source reported as read that the settings switched off, and a claim of typed scoring when that setting is off. The bucket is derived: under 0.5 confidence is "worth asking". The order is fixed: confidence, then PM-owned, then title. `POST /api/schedules/seed` with `set: "brief"` (one press in Today, or `pmos proactive brief schedule`) makes the daily 06:45 schedule once; as with every schedule, one made after its time of day runs once within a minute. The routes make no model or network call and write only the brief file. Typed scoring is a standing opt-in setting that is off by default. Tests: `proactive.test.js` G, H, I and `pm-r22-test.js` B1-B11. The guide page is `guide/proactive-engine.md`.
 
+## Find knowledge without reading whole files (`knowledge-graph`, slice K1)
+
+`pmos kg find|card|neighbors|section|why|stats` builds a map of the repository's tracked Markdown files from relations they already write down (links, frontmatter paths, `D<nn>` citations, `initiative_id`, `parent_kr`) and answers from it, so an agent reads one card or one section and not a 130 KB file. `lib/kg.js` is pure; `lib/kg-cli.js` reads the files, keeps the map in the runtime state directory (rebuilt when HEAD or an uncommitted `.md` changes) and writes nothing in the repository. A link to a missing file is listed as dangling and is never an edge; `lib/kg-dangling-rules.json` says which dangling links are history by design. It does not guess, use embeddings, or call a model or the network. `node scripts/kg-bench.js` replays two written strategies over the fixed questions in `planning/evals/knowledge-graph-questions.md`; it is a simulation, and says "NOT REPORTABLE" until three of the questions are the PM's. Guide page: `guide/knowledge-graph.md`. Tests: `kg.test.js`.
+
+## Background prepare (`proactive-engine`, slice D3)
+
+From a Today item that names an initiative the PM can approve **one plan hash**: the step an agent may do now, with the exact first input. The server queues that approval (`prepare-queue.jsonl` in the runtime state directory) and a 60-second tick starts it through the same `startWork` path as the C1 "go" button — origin `next-step`, the same propose-only rules, the same session budget — only when the switch is on (default off), it is not quiet hours, the budget allows, and the plan hash has not changed. An approval expires after 24 hours, at most 5 can be queued, and a changed plan is skipped, never run. `lib/prepare-queue.js` holds the pure rules (`fold`, `checkRequest`, `canQueue`, `decide`); the routes are `/api/proactive/prepare/{plan,queue,cancel,run}` and `GET /api/proactive/prepare`; `pmos proactive prepare plan|queue|status|cancel|run` is the terminal face. "Run now" ignores quiet hours only. The C1 run record carries `via: 'background'`. Guide page: `guide/proactive-engine.md`. Tests: `proactive-prepare.test.js` (server, CLI, boundary) and `pm-r25-test.js` (browser). Not verified here: a real `claude` session doing the work; the suites use a stand-in agent that records what it was typed.
+
 ## Scheduled tasks from the terminal (`schedule-cli`)
 
 `pmos schedule` and `pmos skill` talk to the running workspace server, so the terminal and the workspace share one schedule store and one validator. Every change is saved the moment the command succeeds. A refused value names what is allowed and changes nothing. With no server running the command says so and exits 1.

package/workspace/bin/pmos.js

@@ -402,6 +402,10 @@ function doctor() {
     code = await require('../lib/proactive-cli').run(process.argv.slice(2), {
       say, call: async (m, p, b) => (port ? api(port, m, p, b) : null) });
   }
+  else if (cmd === 'kg') {
+    // Reads tracked .md files straight from disk (lib/kg-cli.js); needs no running server.
+    code = require('../lib/kg-cli').run(process.argv.slice(2), { say });
+  }
   else if (cmd === 'upgrade') {
     // Escape hatch: pull the latest bundled app and force-reinstall over this global copy. Delegates
     // to the scaffolder (which owns the install path) rather than reinstalling itself in place.
@@ -413,12 +417,13 @@ function doctor() {
     if (r.error) { say('✗ could not run ' + npx + ' — ' + r.error.message); code = 1; }
     else code = r.status === null ? 1 : r.status;
   } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill|proactive]');
+    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill|proactive|kg]');
     say('  pmos          open the current repo as a workspace (starts the server if needed)');
     say('  pmos <path>   open another repo as a workspace');
     say('  pmos schedule …  create, edit and run scheduled tasks (pmos schedule --help)');
     say('  pmos skill …     list, read, create and edit skills');
     say('  pmos proactive … what is waiting for you, feedback, settings (pmos proactive --help)');
+    say('  pmos kg …       find a card, a section or a decision\'s citers without reading whole files (pmos kg --help)');
     say('  pmos upgrade  reinstall the workspace app from the latest published create-pmos');
     code = 0;
   } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {

package/workspace/guide/index.md

@@ -38,3 +38,4 @@ The workspace has three columns. [Layout](layout.md) explains where things open.
 - [Scheduled tasks and the command line](scheduled-tasks-and-cli.md): how to make, edit and run scheduled tasks.
 - [Validate a repository](validate-with-typesafe.md): what each kind of document is compared with, how to read the verdict, and what leaves your machine.
 - [Today and the proactive engine](proactive-engine.md): what Today finds, what you can do with an item, the settings, the commands and the limits.
+- [Find knowledge without reading whole files](knowledge-graph.md): what `pmos kg` finds, its commands, how to read its numbers, and its limits.

package/workspace/guide/knowledge-graph.md

@@ -0,0 +1,63 @@
+---
+type: Guide
+title: "Guide: find knowledge without reading whole files"
+timestamp: 2026-10-03
+---
+
+# Guide: find knowledge without reading whole files
+
+`pmos kg` reads the Markdown files of a repository and builds a map of how they point at each other. You use the map to find one card, one section or one decision's readers. You do not need to open a long file.
+
+## What it is, and what it is not
+
+A **card** is a short summary of one file: its title, its type, its `description` (or its first paragraph) and its size in tokens. A **section** is the lines under one heading.
+
+The map has an **edge** only where a file states a relation:
+
+| Edge | What states it |
+|---|---|
+| link | A Markdown link to a tracked file. |
+| frontmatter | A path in `prd_path`, `rubric_path`, `explainer_path` or `sources`. |
+| supersedes, amended_by, cites | A document that chooses to carry one of these keys. |
+| initiative | An `initiative_id` that names an initiative record. |
+| anchor | A `parent_kr` of `health:<id>` or a KR id. |
+| cites (mention) | A `D<nn>` in the text, such as `D65`, with two or more digits. |
+
+A link that points at a missing file is **dangling**. It is listed and never becomes an edge. A link, a `D<nn>` or a heading inside a code block or a code span is not read.
+
+It does not guess. A file that talks about a topic without a link, a path or a `D<nn>` is not connected to it. It does not use embeddings or a model, and it does not use the network.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `pmos kg find <term>` | Lists cards whose id, title, headings or card contain the term, with the token size of each file. |
+| `pmos kg card <id>` | Prints one card and the headings of the file with their line ranges. |
+| `pmos kg neighbors <id> [--type T] [--depth 1\|2]` | Lists the files that link to this file or that it links to, with the type and the basis of each edge. |
+| `pmos kg section <path>#<heading>` | Prints only that section. `pmos kg section <path> <from>-<to>` prints a line range. |
+| `pmos kg why <D-id>` | Prints the decision's ADR view, its line in the amendment log of `DECISIONS.md`, and the files that cite it, grouped by kind. |
+| `pmos kg stats` | Prints counts: files, edges by type, written and derived cards, files with no incoming link, and the dangling links. |
+
+Add `--max-tokens N` to stop printing at a result boundary. The command then says how many results it did not show.
+
+An unknown file, heading or decision stops with a message that says what was not found. The exit code is 1.
+
+## What the numbers mean
+
+- A token count is the number of characters divided by four. It is an estimate.
+- `stats` splits dangling links into **history by design** and **needs a decision**. The rules are in `workspace/lib/kg-dangling-rules.json`. Read the file and change it if you disagree. A link in `okf/log.md` or in a decision about a removed document is history.
+- A file with no incoming link is not an error. It means no other file links to it.
+- A **derived** card comes from the first paragraph of a file that has no `description`.
+
+## Where the map is kept
+
+The command reads the tracked `.md` files of the Git repository you run it in. It keeps the map in the runtime state directory of the workspace, never in the repository. It builds the map again when the Git HEAD changes or when you edit a tracked `.md` file that is not yet committed. It does not use the cache for any other change.
+
+The command does not edit a file in the repository.
+
+## Limits
+
+- It finds only relations that are written in the files.
+- It reads Markdown files. It does not read the ledgers in `pmos/state/`, a connector, or a session.
+- `find` matches the words you type. It does not know that two different words mean the same thing.
+- The benchmark in `scripts/kg-bench.js` replays two written strategies over fixed questions. It is a simulation. It does not measure the tokens of a real agent session.

package/workspace/guide/proactive-engine.md

@@ -22,6 +22,23 @@ The top of Today is the morning brief: a greeting, the day's calendar, the prior
 - A brief is refused, with the reason and with nothing stored, when it has a wrong shape, an unknown source, a confidence outside 0 to 1, more than 12 items or 20 events, or a text field that is too long.
 - The brief is stored in the workspace state folder on this computer. It is not committed.
 
+## Background preparation
+
+From a Today item that names an initiative, you can ask for the plan and approve it. The workspace then starts that session itself, later. It uses the same path as the next-step go button, so the plan, the prompt, the propose-only rules and the session budget are the same.
+
+- Press **prepare in the background** on an item. Today shows the step an agent session may work on now, where the work would happen, the budget and the exact first input. Press **queue it** to approve that plan.
+- Background prepare is off by default. Turn it on in the settings. When it is off, nothing can be queued and nothing queued is started. A queued entry waits while it is off. It is not dropped.
+- The approval is for one plan. If the plan has changed when the workspace is ready to start, the entry is skipped and the reason is shown. Queue it again to approve the new plan.
+- An approval expires after 24 hours. An expired entry is never started.
+- The workspace starts an entry only when the switch is on, it is not quiet hours, the session budget allows it, and the plan is the one you approved. If the budget is full, the entry waits. Entries start oldest first. At most 5 entries wait at once.
+- **run the queue now** looks at the queue immediately. It ignores quiet hours and nothing else.
+- A queued entry can be cancelled. A cancelled entry is never started.
+- The session starts with no profile, so it names no outside source, and with typed scoring off. It commits only to a local initiative branch or writes drafts. It does not push, open a pull request, send, post, accept, approve a contract or merge. The contract, acceptance and open items are your steps and cannot be queued.
+- A started session counts in the same session budget as a next-step go. Switch to it from Today, and review it from the initiative as for any prepared step.
+- It runs only while the workspace server runs. The queue is stored in the workspace state folder on this computer.
+
+The states of an entry are queued, started, skipped, expired and cancelled.
+
 ## What it shows
 
 Today scans for five conditions. Each one becomes one item with the reason and the evidence.
@@ -52,6 +69,7 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 | engine on | Off stops automatic scans. The scan now button still works. |
 | watch: needs, returned, review, schedule, stalled | Turn one trigger off. |
 | brief sources | One switch for each of calendar, wispr, mail, jira and confluence. |
+| background prepare | Off by default. On lets the workspace start a session for a plan you approved. |
 | typed scoring | Off by default. On lets the skill send titles and metadata to the Typesafe service. |
 | name | Used in the greeting. |
 | stalled after N days | The stalled threshold, from 1 to 90 days. |
@@ -62,14 +80,15 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 
 - `pmos proactive today` lists the items.
 - `pmos proactive scan` scans now.
-- `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
+- `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--background-prepare on|off`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
 - `pmos proactive brief` shows today's brief. `pmos proactive brief submit --file PATH` submits one. `pmos proactive brief schedule` makes the 06:45 schedule for the current repository.
+- `pmos proactive prepare` shows the queue. `pmos proactive prepare plan --initiative ID` shows a plan and its hash. `pmos proactive prepare queue --initiative ID --item ITEM --sha HASH` approves it. `pmos proactive prepare cancel ID` cancels an entry. `pmos proactive prepare run` looks at the queue now.
 - `pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed` records feedback. Use `--missed "text"` for a missed item.
 
 ## Limits
 
 - It runs only while the workspace server runs. It does not catch up for time the server was off. A sleeping computer gets no scan.
 - The items from the records come from this computer. The workspace itself does not read your mail or your calendar. Only the morning-brief session does, and only the sources you switched on.
-- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback.
+- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
 - An unreadable repository is listed as not read. An empty list is not proof that nothing waits there.
 - The records stay in the workspace state folder on this computer. They are not committed.

package/workspace/lib/kg-cli.js

@@ -0,0 +1,146 @@
+'use strict';
+/* kg-cli.js — `pmos kg …`: query the repository's knowledge graph from the terminal (knowledge-graph K1).
+ *
+ *   pmos kg find <term>                          cards whose id, title, headings or card match, with their token cost
+ *   pmos kg card <id>                            one card
+ *   pmos kg neighbors <id> [--type T] [--depth 1|2]
+ *   pmos kg section <path>#<heading>             the lines of one section
+ *   pmos kg section <path> <from>-<to>           a line range
+ *   pmos kg why <D-id>                           the decision's ADR view, its amendment-log line, and the files citing it
+ *   pmos kg stats                                counts, not claims
+ *   --max-tokens N                               stop at a card boundary and say how many results were not shown
+ *
+ * Reads the repository's tracked .md files straight from disk — no server, no model, no network. The graph is cached in
+ * the runtime state directory (never in the repository), keyed by git HEAD plus the modification times of uncommitted
+ * .md files, so a stale graph is rebuilt and a pull request never carries a graph diff. The only write is that cache.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const Kg = require('./kg');
+const { defaultRoot } = require('./state-root');
+const { parseArgs } = require('./schedule-cli');
+
+const COMMANDS = ['find', 'card', 'neighbors', 'section', 'why', 'stats'];
+const RULES_FILE = path.join(__dirname, 'kg-dangling-rules.json');
+const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+
+function repoRoot(cwd) { return git(cwd, ['rev-parse', '--show-toplevel']).trim(); }
+
+function loadFiles(root) {
+  const out = []; const unreadable = [];
+  for (const rel of git(root, ['ls-files', '-z', '*.md']).split('\0').filter(Boolean)) {
+    try { out.push({ path: rel, text: fs.readFileSync(path.join(root, rel), 'utf8') }); }
+    catch (e) { unreadable.push({ path: rel, error: e.code || e.message }); }
+  }
+  return { files: out, unreadable };
+}
+
+function cacheKey(root) {
+  const head = git(root, ['rev-parse', 'HEAD']).trim();
+  const dirty = git(root, ['status', '--porcelain', '-z', '--untracked-files=no']).split('\0').filter(Boolean)
+    .map((l) => l.slice(3)).filter((p) => /\.md$/.test(p)).sort()
+    .map((p) => { try { return p + ':' + fs.statSync(path.join(root, p)).mtimeMs; } catch { return p + ':gone'; } });
+  return crypto.createHash('sha1').update(head + '\n' + dirty.join('\n')).digest('hex');
+}
+
+function graphFor(root, { stateDir = defaultRoot() } = {}) {
+  const dir = path.join(stateDir, 'kg');
+  const file = path.join(dir, crypto.createHash('sha1').update(root).digest('hex').slice(0, 12) + '.json');
+  const key = cacheKey(root);
+  try { const c = JSON.parse(fs.readFileSync(file, 'utf8')); if (c.key === key) return { graph: c.graph, unreadable: c.unreadable, cached: true }; } catch { /* rebuild */ }
+  const { files, unreadable } = loadFiles(root);
+  const graph = Kg.build(files);
+  try { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(file, JSON.stringify({ key, graph, unreadable })); } catch { /* the cache is an optimisation, never required */ }
+  return { graph, unreadable, cached: false };
+}
+
+function run(argv, { say, cwd = process.cwd(), stateDir } = {}) {
+  const [group, verb, ...rest] = argv;
+  const { pos, flags } = parseArgs(rest);
+  const fail = (m) => { say('✗ ' + m); return 1; };
+  if (group !== 'kg' || !verb || flags.help || verb === 'help') { say(`usage: pmos kg <${COMMANDS.join('|')}> …  [--max-tokens N]`); return verb ? 0 : 1; }
+  if (!COMMANDS.includes(verb)) return fail(`unknown command "${verb}" — use ${COMMANDS.join(', ')}`);
+  let root;
+  try { root = repoRoot(cwd); } catch { return fail('this is not a git repository, so there are no tracked files to read'); }
+  const { graph, unreadable, cached } = graphFor(root, { stateDir });
+  const budget = flags['max-tokens'] === undefined ? Infinity : Number(flags['max-tokens']);
+  if (!(budget > 0)) return fail('--max-tokens takes a positive number');
+  for (const u of unreadable || []) say(`not read — ${u.path}: ${u.error}`);
+
+  /* print blocks until the budget is spent, stopping at a block boundary; say how many were not shown */
+  const emit = (blocks) => {
+    let used = 0; let shown = 0;
+    for (const b of blocks) {
+      const cost = Kg.estTokens(b);
+      if (shown && used + cost > budget) break;
+      say(b); used += cost; shown++;
+    }
+    if (shown < blocks.length) say(`… ${blocks.length - shown} more result(s) not shown (--max-tokens ${budget}). ~${used} tokens printed.`);
+    else if (budget !== Infinity) say(`~${used} tokens printed.`);
+  };
+
+  if (verb === 'find') {
+    if (!pos[0]) return fail('find needs a term');
+    const hits = Kg.find(graph, pos.join(' '), { limit: 50 });
+    if (!hits.length) { say(`nothing matches "${pos.join(' ')}"`); return 0; }
+    emit(hits.map((h) => `${Kg.cardText(h.node)}\n    matched: ${h.where.join(', ')} · linked from ${h.indegree} file(s)`));
+    return 0;
+  }
+  if (verb === 'card') {
+    const n = Kg.nodeById(graph, pos[0]);
+    if (!n) return fail(`no file "${pos[0] || ''}" in the graph`);
+    say(Kg.cardText(n));
+    for (const h of n.headings) say(`${'  '.repeat(h.level - 1)}${h.text}  (lines ${h.start}-${h.end})`);
+    return 0;
+  }
+  if (verb === 'neighbors') {
+    const depth = flags.depth === undefined ? 1 : Number(flags.depth);
+    if (![1, 2].includes(depth)) return fail('--depth takes 1 or 2');
+    const rows = Kg.neighbors(graph, pos[0], { type: flags.type || null, depth });
+    if (!rows) return fail(`no file "${pos[0] || ''}" in the graph`);
+    if (!rows.length) { say('no neighbours' + (flags.type ? ` of type ${flags.type}` : '')); return 0; }
+    emit(rows.map((r) => `${r.direction === 'out' ? '→' : '←'} ${r.via} (${r.basis}${r.depth > 1 ? ', depth ' + r.depth : ''})  ${Kg.cardText(Kg.nodeById(graph, r.id))}`));
+    return 0;
+  }
+  if (verb === 'section') {
+    let id = pos[0] || ''; let spec = pos[1] || '';
+    const hash = id.indexOf('#');
+    if (hash > 0) { spec = id.slice(hash); id = id.slice(0, hash); }
+    const n = Kg.nodeById(graph, id);
+    if (!n) return fail(`no file "${id}" in the graph`);
+    if (!spec) return fail('section needs #heading or from-to');
+    const s = Kg.section(n, fs.readFileSync(path.join(root, id), 'utf8'), spec);
+    if (!s) return fail(`no section "${spec}" in ${id} — run: pmos kg card ${id}`);
+    say(`${id} lines ${s.from}-${s.to} (~${Kg.estTokens(s.text)} tokens of ${n.tokens_est})`);
+    say(s.text);
+    return 0;
+  }
+  if (verb === 'why') {
+    const w = Kg.why(graph, pos[0]);
+    if (!w) return fail(`no decision "${pos[0] || ''}" — the ADR views are okf/products/pmos/adr/dNN-*.md`);
+    say(Kg.cardText(w.adr));
+    say(w.amendmentLog ? `amendment log: ${w.amendmentLog.path} line ${w.amendmentLog.line}` : 'amendment log: no "Added **D…**" line found');
+    const blocks = [];
+    for (const [kind, rows] of Object.entries(w.citedBy).sort()) blocks.push(`${kind} (${rows.length}):\n` + rows.map((r) => `  ${r.id}  [${r.via.join('+')}, ${r.basis}]`).join('\n'));
+    emit(blocks.length ? blocks : ['no file cites this decision']);
+    return 0;
+  }
+  if (verb === 'stats') {
+    const rules = JSON.parse(fs.readFileSync(RULES_FILE, 'utf8'));
+    const s = Kg.stats(graph, rules);
+    say(`${s.nodes} files, ${s.edges} edges (${s.byBasis.stated} stated, ${s.byBasis.mention} mention) — graph ${cached ? 'from cache' : 'rebuilt'}`);
+    say('edges by type: ' + Object.entries(s.byType).sort().map(([k, v]) => `${k} ${v}`).join(', '));
+    say(`cards: ${s.cardsWritten} written (description), ${s.cardsDerived} derived from the first paragraph, ${s.noCard} none`);
+    say(`${s.noType} file(s) have no type · ${s.noIncoming} have no incoming link (index and log files excluded)`);
+    say(`dangling links: ${s.dangling} — ${s.danglingHistory} history by design (${path.relative(root, RULES_FILE) || RULES_FILE}), ${s.danglingNeedsDecision} need a decision`);
+    for (const d of s.needsDecision) say(`  ${d.from} → ${d.to}`);
+    say('Only relations written in the files are found. Token counts are characters ÷ 4, an estimate.');
+    return 0;
+  }
+  return 0;
+}
+
+module.exports = { run, graphFor, loadFiles, cacheKey, COMMANDS };

package/workspace/lib/kg-dangling-rules.json

@@ -0,0 +1,6 @@
+[
+  { "from": "^okf/log\\.md$", "why": "the OKF log records references to documents that were removed on purpose" },
+  { "from": "^okf/products/pmos/", "to": "(mcp-tools|data-model|references/metrics/v_)", "why": "D66 deleted the hosted-backend reference documents; the text that cites them is history" },
+  { "from": "/blind-plants/", "why": "a blind-plant specimen is planted with broken references on purpose" },
+  { "to": "^/planning/prd/x\\.md$", "why": "an example path in an explainer, not a reference" }
+]

package/workspace/lib/kg.js

@@ -0,0 +1,266 @@
+'use strict';
+/* kg.js — the repository's knowledge graph, derived from what its files already state (knowledge-graph K1).
+ *
+ * Pure: takes [{path, text}] for the tracked Markdown files and returns nodes, edges and the dangling links.
+ * No filesystem, no git, no network, no model. Same input → byte-identical output.
+ *
+ * WHAT IS A NODE. One tracked .md file. It carries a CARD (the frontmatter `description`, else the first paragraph,
+ * cut at 240 characters), a token estimate (characters ÷ 4 — an estimate, not a measurement), and its headings with
+ * line ranges so a caller can read ONE section and not the file.
+ *
+ * WHAT IS AN EDGE. Only a relation a file writes down:
+ *   link         a Markdown link to a tracked file                                  basis stated
+ *   frontmatter  a path in prd_path / rubric_path / explainer_path / sources        basis stated
+ *   supersedes · amended_by · cites   (typed keys a document opts into)             basis stated
+ *   initiative   initiative_id (frontmatter or an identity bullet) → its record     basis stated
+ *   anchor       parent_kr / parent_KR `health:<id>` or a KR id → the file naming it basis stated
+ *   cites        a `D<nn>` mention in prose → that decision's ADR view              basis mention
+ * A link to a file that does not exist is a DANGLING item, never an edge. A link-like string inside a code fence or
+ * an inline code span is not a relation and makes no edge. Nothing is inferred by similarity; workspace/lib/
+ * related-docs.js took the same position for alignment, for the same reason.
+ *
+ * `D<nn>` needs two or more digits on purpose: slice labels such as "D1" and "D3" in the proactive-engine documents
+ * would otherwise cite decisions D01 and D03 that they never mention.
+ */
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.Kg = api;
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  const CARD_MAX = 240;
+  const ADR_DIR = 'okf/products/pmos/adr/';
+  const PATH_KEYS = ['prd_path', 'rubric_path', 'explainer_path', 'sources'];
+  const TYPED_KEYS = ['supersedes', 'amended_by', 'cites'];
+  const estTokens = (s) => Math.ceil(String(s || '').length / 4);
+
+  /* Replace fenced code blocks and inline code spans with spaces of the same length, keeping every newline, so line
+   * numbers stay true and nothing inside code is read as a link, a citation or a heading. */
+  function stripCode(text) {
+    const blank = (s) => s.replace(/[^\n]/g, ' ');
+    let out = '';
+    let fence = null;
+    for (const line of String(text || '').split('\n')) {
+      const m = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+      if (fence) { out += blank(line) + '\n'; if (m && m[1][0] === fence[0] && m[1].length >= fence.length) fence = null; continue; }
+      if (m) { fence = m[1]; out += blank(line) + '\n'; continue; }
+      out += line.replace(/(`+)[^`\n]*?\1/g, (s) => blank(s)) + '\n';
+    }
+    return out.slice(0, -1);
+  }
+
+  /* Frontmatter values come from the reader workspace/lib/related-docs.js already ships (one-line `key: value`);
+   * the body start line is the only thing computed here. */
+  const readFm = (typeof require === 'function') ? require('./related-docs').frontmatter : null;
+  function frontmatter(text) {
+    const m = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(String(text || ''));
+    if (!m) return { fm: {}, bodyStart: 1 };
+    return { fm: readFm ? readFm(text) : {}, bodyStart: m[0].split('\n').length };
+  }
+
+  function headingsOf(stripped, bodyStart) {
+    const lines = stripped.split('\n');
+    const found = [];
+    for (let i = bodyStart - 1; i < lines.length; i++) {
+      const m = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(lines[i]);
+      if (m) found.push({ level: m[1].length, text: m[2].trim(), start: i + 1 });
+    }
+    for (let k = 0; k < found.length; k++) {
+      let end = lines.length;
+      for (let j = k + 1; j < found.length; j++) if (found[j].level <= found[k].level) { end = found[j].start - 1; break; }
+      found[k].end = end;
+    }
+    return found;
+  }
+
+  function cardOf(fm, stripped, bodyStart) {
+    if (fm.description) return fm.description.slice(0, CARD_MAX);
+    const lines = stripped.split('\n').slice(bodyStart - 1);
+    const para = [];
+    for (const raw of lines) {
+      const l = raw.trim();
+      if (!l) { if (para.length) break; continue; }
+      if (/^(#|\||>|---|[-*]\s|\d+\.\s|<)/.test(l)) { if (para.length) break; continue; }
+      para.push(l);
+    }
+    return para.join(' ').replace(/\[([^\]]+)\]\([^)]*\)/g, '$1').slice(0, CARD_MAX);
+  }
+
+  const norm = (from, target) => {
+    const t = target.replace(/^<|>$/g, '');
+    const parts = (t.startsWith('/') ? t.slice(1) : from.replace(/[^/]*$/, '') + t).split('/');
+    const out = [];
+    for (const p of parts) { if (p === '.' || p === '') continue; if (p === '..') out.pop(); else out.push(p); }
+    return out.join('/');
+  };
+
+  const pathsIn = (value) => [...String(value || '').matchAll(/[\w@./-]+\.md\b/g)].map((m) => m[0].replace(/^\//, ''));
+
+  function build(files) {
+    const list = (files || []).filter((f) => f && typeof f.path === 'string').sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const have = new Set(list.map((f) => f.path));
+    const adrFor = new Map();
+    for (const p of have) { const m = /^okf\/products\/pmos\/adr\/d(\d{2,3})-/.exec(p); if (m) adrFor.set('D' + m[1], p); }
+    const krFile = new Map();
+    for (const f of list) if (f.path.startsWith('planning/okrs/')) for (const m of f.text.matchAll(/\bO\d+\.KR\d+\b/g)) if (!krFile.has(m[0])) krFile.set(m[0], f.path);
+    const budgets = have.has('planning/okrs/health-budgets.md') ? 'planning/okrs/health-budgets.md' : null;
+
+    const nodes = [];
+    const edges = new Map();
+    const dangling = [];
+    const meta = { decisionLines: {} };
+    const addEdge = (from, to, type, basis) => {
+      if (from === to || !have.has(to)) return;
+      const key = from + '\u0000' + to + '\u0000' + type;
+      const cur = edges.get(key);
+      if (!cur) edges.set(key, { from, to, type, basis });
+      else if (cur.basis === 'mention' && basis === 'stated') cur.basis = 'stated';
+    };
+
+    for (const f of list) {
+      const text = String(f.text || '');
+      const { fm, bodyStart } = frontmatter(text);
+      const stripped = stripCode(text);
+      const body = stripped;
+      const heads = headingsOf(stripped, bodyStart);
+      const title = fm.title || (heads.find((h) => h.level === 1) || {}).text || f.path;
+      nodes.push({
+        id: f.path, title, type: fm.type || null, card: cardOf(fm, stripped, bodyStart),
+        described: !!fm.description, tokens_est: estTokens(text), lines: text.split('\n').length,
+        headings: heads.map((h) => ({ level: h.level, text: h.text, start: h.start, end: h.end })),
+        status: fm.status || null, stale_after: fm.stale_after || null,
+      });
+
+      for (const m of body.matchAll(/\]\(([^)\s]+?)(?:#[^)]*)?\)/g)) {
+        const raw = m[1];
+        if (/^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith('#')) continue;
+        if (!/\.md$/i.test(raw)) continue;
+        const to = norm(f.path, raw);
+        if (have.has(to)) addEdge(f.path, to, 'link', 'stated');
+        else dangling.push({ from: f.path, to: raw });
+      }
+      for (const m of body.matchAll(/\bD(\d{2,3})\b/g)) {
+        const to = adrFor.get('D' + m[1]);
+        if (to) addEdge(f.path, to, 'cites', 'mention');
+      }
+      for (const k of PATH_KEYS) for (const p of pathsIn(fm[k])) addEdge(f.path, p, 'frontmatter', 'stated');
+      for (const k of TYPED_KEYS) for (const p of pathsIn(fm[k])) addEdge(f.path, p, k, 'stated');
+      const ini = fm.initiative_id || ((/^[-*]?\s*initiative_id:\s*([\w.-]+)/m.exec(body) || [])[1]);
+      if (ini) addEdge(f.path, 'planning/initiatives/' + ini + '.md', 'initiative', 'stated');
+      const anchor = fm.parent_kr || fm.parent_KR || ((/^[-*]?\s*parent_kr:\s*([\w:.-]+)/im.exec(body) || [])[1]);
+      if (anchor) {
+        if (/^health:/.test(anchor) && budgets) addEdge(f.path, budgets, 'anchor', 'stated');
+        else if (krFile.has(anchor)) addEdge(f.path, krFile.get(anchor), 'anchor', 'stated');
+      }
+      if (f.path === 'DECISIONS.md') {
+        const lines = body.split('\n');
+        for (let i = 0; i < lines.length; i++) { const m = /\bAdded \*\*(D\d{2,3})\*\*/.exec(lines[i]); if (m && !(m[1] in meta.decisionLines)) meta.decisionLines[m[1]] = i + 1; }
+      }
+    }
+    const e = [...edges.values()].sort((a, b) => (a.from + a.to + a.type < b.from + b.to + b.type ? -1 : 1));
+    dangling.sort((a, b) => (a.from + a.to < b.from + b.to ? -1 : a.from + a.to > b.from + b.to ? 1 : 0));
+    return { nodes, edges: e, dangling, meta };
+  }
+
+  /* Split dangling links into "history by design" and "needs a decision" by a readable rule list:
+   * [{from?: regex, to?: regex, why: string}] — a rule matches when every field it names matches. */
+  function splitDangling(graph, rules) {
+    const compiled = (rules || []).map((r) => ({ from: r.from ? new RegExp(r.from) : null, to: r.to ? new RegExp(r.to) : null, why: r.why || '' }));
+    const history = []; const needs = [];
+    for (const d of graph.dangling) {
+      const r = compiled.find((x) => (x.from || x.to) && (!x.from || x.from.test(d.from)) && (!x.to || x.to.test(d.to)));
+      if (r) history.push({ ...d, why: r.why }); else needs.push(d);
+    }
+    return { history, needs };
+  }
+
+  function stats(graph, rules) {
+    const byType = {}; const byBasis = { stated: 0, mention: 0 };
+    for (const e of graph.edges) { byType[e.type] = (byType[e.type] || 0) + 1; byBasis[e.basis]++; }
+    const inbound = new Set(graph.edges.map((e) => e.to));
+    const orphans = graph.nodes.filter((n) => !inbound.has(n.id) && !/(^|\/)(index|log)\.md$/.test(n.id)).length;
+    const split = splitDangling(graph, rules);
+    return {
+      nodes: graph.nodes.length, edges: graph.edges.length, byType, byBasis,
+      cardsWritten: graph.nodes.filter((n) => n.described).length,
+      cardsDerived: graph.nodes.filter((n) => !n.described && n.card).length,
+      noCard: graph.nodes.filter((n) => !n.card).length,
+      noType: graph.nodes.filter((n) => !n.type).length,
+      noIncoming: orphans, dangling: graph.dangling.length,
+      danglingHistory: split.history.length, danglingNeedsDecision: split.needs.length, needsDecision: split.needs,
+    };
+  }
+
+  const nodeById = (graph, id) => graph.nodes.find((n) => n.id === id) || null;
+  const cardText = (n) => `${n.id} [${n.type || 'untyped'}] ${n.title}${n.card ? ' — ' + n.card : ''} (file ~${n.tokens_est} tokens)`;
+
+  /* Rank: where the term matches (id 3, title 3, heading 2, card 1), then how many files link to the node. */
+  function find(graph, term, { limit = 20 } = {}) {
+    const t = String(term || '').toLowerCase().trim();
+    if (!t) return [];
+    const indeg = new Map();
+    for (const e of graph.edges) indeg.set(e.to, (indeg.get(e.to) || 0) + 1);
+    const out = [];
+    for (const n of graph.nodes) {
+      let score = 0; const where = [];
+      if (n.id.toLowerCase().includes(t)) { score += 3; where.push('id'); }
+      if (n.title.toLowerCase().includes(t)) { score += 3; where.push('title'); }
+      const h = n.headings.find((x) => x.text.toLowerCase().includes(t));
+      if (h) { score += 2; where.push('heading "' + h.text + '"'); }
+      if ((n.card || '').toLowerCase().includes(t)) { score += 1; where.push('card'); }
+      if (score) out.push({ node: n, score, where, indegree: indeg.get(n.id) || 0 });
+    }
+    return out.sort((a, b) => b.score - a.score || b.indegree - a.indegree || (a.node.id < b.node.id ? -1 : 1)).slice(0, limit);
+  }
+
+  function neighbors(graph, id, { type = null, depth = 1 } = {}) {
+    if (!nodeById(graph, id)) return null;
+    const seen = new Map([[id, 0]]); const rows = [];
+    let frontier = [id];
+    for (let d = 1; d <= depth; d++) {
+      const next = [];
+      for (const e of graph.edges) {
+        if (type && e.type !== type) continue;
+        for (const [a, b, dir] of [[e.from, e.to, 'out'], [e.to, e.from, 'in']]) {
+          if (!frontier.includes(a) || seen.has(b)) continue;
+          seen.set(b, d); next.push(b); rows.push({ id: b, via: e.type, basis: e.basis, direction: dir, depth: d, from: a });
+        }
+      }
+      frontier = next;
+    }
+    return rows;
+  }
+
+  /* why("D65"): the ADR view, the amendment-log line in DECISIONS.md, and every file that cites the ADR, by kind. */
+  function why(graph, dId) {
+    const id = String(dId || '').toUpperCase().replace(/^D(\d)$/, 'D0$1');
+    const adr = graph.nodes.find((n) => n.id.startsWith(ADR_DIR + id.toLowerCase() + '-'));
+    if (!adr) return null;
+    const groups = {};
+    const byFrom = new Map();
+    for (const e of graph.edges) if (e.to === adr.id) {
+      const cur = byFrom.get(e.from) || { id: e.from, via: [], basis: 'mention' };
+      if (!cur.via.includes(e.type)) cur.via.push(e.type);
+      if (e.basis === 'stated') cur.basis = 'stated';
+      byFrom.set(e.from, cur);
+    }
+    for (const r of byFrom.values()) { const n = nodeById(graph, r.id); const k = (n && n.type) || 'untyped'; r.via.sort(); (groups[k] = groups[k] || []).push(r); }
+    for (const k of Object.keys(groups)) groups[k].sort((a, b) => (a.id < b.id ? -1 : 1));
+    const line = graph.meta && graph.meta.decisionLines ? graph.meta.decisionLines[id] || null : null;
+    return { decision: id, adr, amendmentLog: line ? { path: 'DECISIONS.md', line } : null, citedBy: groups };
+  }
+
+  /* section(node, text, spec): spec is "#heading words" or "from-to". Returns {from,to,text} or null. */
+  function section(node, text, spec) {
+    const lines = String(text || '').split('\n');
+    const m = /^(\d+)-(\d+)$/.exec(spec || '');
+    if (m) { const from = Math.max(1, +m[1]); const to = Math.min(lines.length, +m[2]); if (from > to) return null; return { from, to, text: lines.slice(from - 1, to).join('\n') }; }
+    const want = String(spec || '').replace(/^#/, '').trim().toLowerCase();
+    if (!want || !node) return null;
+    const h = node.headings.find((x) => x.text.toLowerCase() === want) || node.headings.find((x) => x.text.toLowerCase().includes(want));
+    if (!h) return null;
+    return { from: h.start, to: h.end, heading: h.text, text: lines.slice(h.start - 1, h.end).join('\n') };
+  }
+
+  return { build, stats, splitDangling, find, neighbors, why, section, nodeById, cardText, stripCode, frontmatter, estTokens, ADR_DIR };
+});

package/workspace/lib/prepare-queue.js

@@ -0,0 +1,76 @@
+'use strict';
+/* prepare-queue.js — the rules for background preparation: what may be queued, and when a queued entry may start.
+ *
+ * Pure: no I/O, no clock, no model. The server passes what is true now (the settings, the entries read from the ledger, a
+ * fresh prepare of the same step, the session budget) and this module decides. An approval is ONE plan hash, never a
+ * standing permission: a plan that changed is skipped, an approval older than 24 hours expires, and nothing is caught up.
+ *
+ *   fold(events)                         → the entries, each with its latest status
+ *   checkRequest(body)                   → the shape of a queue request, or why it is refused
+ *   canQueue({settings, entries, req})   → null, or the reason a request is refused
+ *   decide({entry, now, settings, quiet, manual, fresh, budget}) → {action, reason}
+ *
+ * Statuses: queued · started · skipped · expired · cancelled. Only `queued` can change; the other four are final.
+ */
+const MAX_QUEUED = 5;
+const EXPIRE_MS = 24 * 60 * 60 * 1000;
+const FINAL = ['started', 'skipped', 'expired', 'cancelled'];
+const HASH = /^[0-9a-f]{16}$/;
+const ID = /^[a-z0-9][a-z0-9._-]*$/i;
+const ITEM = /^[\w.:-]{1,120}$/;
+const CAND = /^[0-9a-f]{12}$/;
+
+/** The latest status of every entry, oldest first. A line that names no entry is ignored. */
+function fold(events) {
+  const by = new Map();
+  for (const e of Array.isArray(events) ? events : []) {
+    if (!e || typeof e.id !== 'string') continue;
+    if (e.event === 'queued') { if (!by.has(e.id)) by.set(e.id, { id: e.id, status: 'queued', queued_at: e.at, ws: e.ws, initiative_id: e.initiative_id, item_id: e.item_id, key: e.key, candidate_id: e.candidate_id || null, prompt_sha: e.prompt_sha, branch: e.branch || null, reason: null, session_id: null, at: e.at }); continue; }
+    const cur = by.get(e.id);
+    if (!cur || FINAL.includes(cur.status) || !FINAL.includes(e.event)) continue;
+    cur.status = e.event; cur.reason = e.reason || null; cur.session_id = e.session_id || null; cur.at = e.at;
+  }
+  return [...by.values()];
+}
+
+/** @returns {{ok:true, req:object}|{ok:false, error:string}} */
+function checkRequest(body) {
+  const b = body && typeof body === 'object' ? body : {};
+  if (b.confirm !== true) return { ok: false, error: 'confirm is required: this lets the workspace start a session later' };
+  if (typeof b.ws !== 'string' || !b.ws) return { ok: false, error: 'ws is required' };
+  if (typeof b.initiative_id !== 'string' || !ID.test(b.initiative_id)) return { ok: false, error: 'initiative_id is required' };
+  if (typeof b.item_id !== 'string' || !ITEM.test(b.item_id)) return { ok: false, error: 'item_id is required' };
+  if (typeof b.prompt_sha !== 'string' || !HASH.test(b.prompt_sha)) return { ok: false, error: 'prompt_sha is required: queue the plan you were shown' };
+  if (b.candidate_id !== undefined && b.candidate_id !== null && b.candidate_id !== '' && !CAND.test(String(b.candidate_id))) return { ok: false, error: 'candidate_id is not a candidate id' };
+  return { ok: true, req: { ws: b.ws, initiative_id: b.initiative_id, item_id: b.item_id, prompt_sha: b.prompt_sha, candidate_id: b.candidate_id || null } };
+}
+
+/** @returns {string|null} the reason a request is refused, or null */
+function canQueue({ settings, entries, req }) {
+  if (!settings || settings.backgroundPrepare !== true) return 'background prepare is off. Turn it on in the Today settings first.';
+  const queued = (entries || []).filter((e) => e.status === 'queued');
+  if (queued.some((e) => e.ws === req.ws && e.initiative_id === req.initiative_id && e.item_id === req.item_id)) return 'this step is already queued';
+  if (queued.length >= MAX_QUEUED) return `${queued.length} entries are already waiting (the limit is ${MAX_QUEUED}). Cancel one or wait for it to start.`;
+  return null;
+}
+
+/**
+ * What the runner does with one queued entry right now.
+ * @param {{entry:object, now:number, settings:object, quiet:boolean, manual:boolean, fresh:object, budget:object}} s
+ * @returns {{action:'start'|'wait'|'skip'|'expire', reason:string|null}}
+ */
+function decide(s) {
+  const e = s.entry;
+  const age = s.now - Date.parse(e.queued_at);
+  if (!Number.isFinite(age) || age > EXPIRE_MS) return { action: 'expire', reason: 'the approval is older than 24 hours — queue it again if you still want it' };
+  if (!s.settings || s.settings.backgroundPrepare !== true) return { action: 'wait', reason: 'background prepare is off' };
+  if (s.quiet && !s.manual) return { action: 'wait', reason: 'quiet hours' };
+  const f = s.fresh || {};
+  if (!f.ok) return { action: 'skip', reason: f.error || 'the step could not be prepared again' };
+  if (f.refused) return { action: 'skip', reason: f.refused.why };
+  if (f.prompt_sha !== e.prompt_sha) return { action: 'skip', reason: 'the plan changed since you approved it — queue it again to approve the new one' };
+  if (!s.budget || !s.budget.allowed) return { action: 'wait', reason: (s.budget && s.budget.reason) || 'no session budget' };
+  return { action: 'start', reason: null };
+}
+
+module.exports = { MAX_QUEUED, EXPIRE_MS, FINAL, fold, checkRequest, canQueue, decide };

package/workspace/lib/proactive-cli.js

@@ -13,13 +13,16 @@
  *   pmos proactive brief [show]
  *   pmos proactive brief submit --file PATH
  *   pmos proactive brief schedule [--repo PATH]
+ *   pmos proactive prepare plan --initiative ID [--repo PATH]
+ *   pmos proactive prepare queue --initiative ID --item ITEM --sha HASH [--repo PATH]
+ *   pmos proactive prepare status | cancel ID | run
  */
 const fs = require('fs');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const { parseArgs } = require('./schedule-cli');
 
-const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief'] };
+const COMMANDS = { proactive: ['today', 'scan', 'settings', 'feedback', 'brief', 'prepare'] };
 const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
 const onOff = (v, what) => (v === 'on' || v === 'true' ? true : v === 'off' || v === 'false' ? false : { err: `${what} takes on or off` });
 
@@ -63,6 +66,7 @@ async function run(argv, { call, say, cwd = process.cwd() }) {
       patch.triggers = { [m[1]]: m[2] === 'on' };
     }
     if ('name' in flags) patch.name = flags.name;
+    if ('background-prepare' in flags) { const v = onOff(flags['background-prepare'], '--background-prepare'); if (v.err) return fail(v.err); patch.backgroundPrepare = v; }
     if ('brief-scoring' in flags) { const v = onOff(flags['brief-scoring'], '--brief-scoring'); if (v.err) return fail(v.err); patch.briefScoring = v; }
     if ('brief-source' in flags) {
       const m = /^([a-z]+)=(on|off)$/.exec(flags['brief-source']);
@@ -82,9 +86,61 @@ async function run(argv, { call, say, cwd = process.cwd() }) {
     }
     say(`engine ${s.enabled ? 'on' : 'off'} · stalled after ${s.stalledDays} days · quiet ${s.quiet ? s.quiet.start + '-' + s.quiet.end : 'none'} · learning ${s.pauseLearning ? 'paused' : 'on'}`);
     say('brief sources: ' + BRIEF_SOURCES.map((k) => `${k} ${s.briefSources && s.briefSources[k] ? 'on' : 'off'}`).join(', ') + ' · scoring ' + (s.briefScoring ? 'on' : 'off') + (s.name ? ' · name ' + s.name : ''));
+    say('background prepare ' + (s.backgroundPrepare ? 'on' : 'off'));
     say('watching: ' + Object.entries(s.triggers).map(([k, v]) => `${k} ${v ? 'on' : 'off'}`).join(', '));
     return 0;
   }
+  if (verb === 'prepare') {
+    const sub = pos[0] || 'status';
+    const wsOf = async () => {
+      let root; try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: flags.repo ? path.resolve(cwd, flags.repo) : cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return { err: 'this is not inside a git repository — use --repo PATH' }; }
+      const wl = await call('GET', '/api/workspaces');
+      const hit = ((wl && wl.workspaces) || []).find((w) => path.resolve(w.root) === path.resolve(root));
+      return hit ? { ws: hit.id } : { err: `${root} is not a registered workspace — open it with pmos first` };
+    };
+    if (sub === 'plan' || sub === 'queue') {
+      if (!flags.initiative) return fail(`usage: pmos proactive prepare ${sub} --initiative ID${sub === 'queue' ? ' --item ITEM --sha HASH' : ''}`);
+      const w = await wsOf(); if (w.err) return fail(w.err);
+      if (sub === 'plan') {
+        const r = await call('POST', '/api/proactive/prepare/plan', { ws: w.ws, initiative_id: flags.initiative });
+        if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+        say(`step: ${r.item.key} — ${r.item.text}  (item ${r.item.id})`);
+        if (r.refused) { say('refused: ' + r.refused.why); return 1; }
+        say(r.plan.why || r.plan.plan);
+        say(`budget: ${r.budget.running} of ${r.budget.limits.concurrent} running · ${r.budget.startedToday} of ${r.budget.limits.perDay} started today`);
+        say('background prepare is ' + (r.background.enabled ? 'on' : 'off. Turn it on with: pmos proactive settings --background-prepare on'));
+        say('plan ' + r.prompt_sha + ' — the exact first input:');
+        say(r.prompt);
+        say(`queue it with: pmos proactive prepare queue --initiative ${r.initiative_id} --item ${r.item.id} --sha ${r.prompt_sha}`);
+        return 0;
+      }
+      if (!flags.item || !flags.sha) return fail('usage: pmos proactive prepare queue --initiative ID --item ITEM --sha HASH');
+      const r = await call('POST', '/api/proactive/prepare/queue', { ws: w.ws, initiative_id: flags.initiative, item_id: flags.item, prompt_sha: flags.sha, confirm: true });
+      if (!r || r.ok === false) return fail(`refused — ${(r && r.error) || 'the server did not answer'}. Nothing was queued.`);
+      say(`queued ${r.entry.id} — the workspace starts it when the budget allows. It expires in 24 hours.`);
+      return 0;
+    }
+    if (sub === 'cancel') {
+      if (!pos[1]) return fail('usage: pmos proactive prepare cancel ID');
+      const r = await call('POST', '/api/proactive/prepare/cancel', { id: pos[1] });
+      if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+      say('cancelled'); return 0;
+    }
+    if (sub === 'run') {
+      const r = await call('POST', '/api/proactive/prepare/run', {});
+      if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+      if (!r.results.length) say('nothing is queued');
+      for (const x of r.results) say(`${x.id}  ${x.action}${x.reason ? ' — ' + x.reason : ''}${x.session_id ? ' (session ' + x.session_id + ')' : ''}`);
+      return 0;
+    }
+    if (sub !== 'status') return fail('usage: pmos proactive prepare [status|plan|queue|cancel ID|run]');
+    const r = await call('GET', '/api/proactive/prepare');
+    if (!r || r.ok === false) return fail((r && r.error) || 'the server did not answer');
+    say(`background prepare ${r.enabled ? 'on' : 'off'}${r.quiet ? ' · quiet hours now' : ''} · ${r.budget.running} of ${r.budget.limits.concurrent} running · ${r.budget.startedToday} of ${r.budget.limits.perDay} started today`);
+    if (!r.entries.length) say('nothing has been queued');
+    for (const e of r.entries) say(`${e.id}  ${e.status}  ${e.label}${e.reason ? ' — ' + e.reason : ''}`);
+    return 0;
+  }
   if (verb === 'brief') {
     const sub = pos[0] || 'show';
     if (sub === 'submit') {

package/workspace/lib/proactive.js

@@ -32,7 +32,7 @@ const OWNER = { needs: 'pm', returned: 'pm', review: 'pm', schedule: 'pm', stall
 const BRIEF_SOURCES = ['calendar', 'wispr', 'mail', 'jira', 'confluence'];
 // Mail is off by default: a brief reads titles and metadata of the other sources, and the PM turns mail on.
 const BRIEF_DEFAULT = Object.freeze({ calendar: true, wispr: true, mail: false, jira: true, confluence: true });
-const DEFAULTS = Object.freeze({ name: '', briefSources: BRIEF_DEFAULT, briefScoring: false, enabled: true, triggers: Object.freeze(Object.fromEntries(TRIGGERS.map((t) => [t, true]))), stalledDays: 5, quiet: null, pauseLearning: false });
+const DEFAULTS = Object.freeze({ name: '', briefSources: BRIEF_DEFAULT, briefScoring: false, backgroundPrepare: false, enabled: true, triggers: Object.freeze(Object.fromEntries(TRIGGERS.map((t) => [t, true]))), stalledDays: 5, quiet: null, pauseLearning: false });
 
 const idOf = (key) => crypto.createHash('sha1').update(String(key)).digest('hex').slice(0, 12);
 const clip = (s, n) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
@@ -161,10 +161,11 @@ const HHMM = /^([01]\d|2[0-3]):([0-5]\d)$/;
 /** @returns {{ok:true, settings:object}|{ok:false, error:string}} — `raw` is merged over the defaults; nothing is partly applied. */
 function normalizeSettings(raw) {
   const r = raw && typeof raw === 'object' ? raw : {};
-  const s = { name: DEFAULTS.name, briefSources: { ...BRIEF_DEFAULT }, briefScoring: DEFAULTS.briefScoring, enabled: DEFAULTS.enabled, triggers: { ...DEFAULTS.triggers }, stalledDays: DEFAULTS.stalledDays, quiet: DEFAULTS.quiet, pauseLearning: DEFAULTS.pauseLearning };
+  const s = { name: DEFAULTS.name, briefSources: { ...BRIEF_DEFAULT }, briefScoring: DEFAULTS.briefScoring, backgroundPrepare: DEFAULTS.backgroundPrepare, enabled: DEFAULTS.enabled, triggers: { ...DEFAULTS.triggers }, stalledDays: DEFAULTS.stalledDays, quiet: DEFAULTS.quiet, pauseLearning: DEFAULTS.pauseLearning };
   if (r.enabled !== undefined) { if (typeof r.enabled !== 'boolean') return { ok: false, error: 'enabled must be true or false' }; s.enabled = r.enabled; }
   if (r.name !== undefined) { if (typeof r.name !== 'string' || r.name.length > 40) return { ok: false, error: 'name must be text of at most 40 characters' }; s.name = r.name.replace(/\s+/g, ' ').trim(); }
   if (r.briefScoring !== undefined) { if (typeof r.briefScoring !== 'boolean') return { ok: false, error: 'briefScoring must be true or false' }; s.briefScoring = r.briefScoring; }
+  if (r.backgroundPrepare !== undefined) { if (typeof r.backgroundPrepare !== 'boolean') return { ok: false, error: 'backgroundPrepare must be true or false' }; s.backgroundPrepare = r.backgroundPrepare; }
   if (r.briefSources !== undefined) {
     if (!r.briefSources || typeof r.briefSources !== 'object' || Array.isArray(r.briefSources)) return { ok: false, error: `briefSources must be an object of ${BRIEF_SOURCES.join(', ')} → true or false` };
     for (const [k, v] of Object.entries(r.briefSources)) {

package/workspace/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",
@@ -10,12 +10,12 @@
   "scripts": {
     "start": "node server.js",
     "test": "node test.js && npm run test:modules",
-    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node jev-claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js",
+    "test:modules": "node proactive.test.js && node focus.test.js && node handoff.test.js && node repo-scan.test.js && node profiles.test.js && node external-linking.test.js && node story-artifacts.test.js && node no-network.test.js && node typesafe-validation.test.js && node claims.test.js && node jev-claims.test.js && node repo-watch.test.js && node fixture-parity.test.mjs && node markdown.test.mjs && node start-policy.test.js && node state-isolation.test.js && node sync.test.js && node schedule-cli.test.js && node initiative-surface.test.js && node guide.test.js && node next-step-actions.test.js && node kg.test.js && node proactive-prepare.test.js",
     "test:ui": "node ui-test.js",
     "test:parity": "node design-parity.js --states",
     "test:all": "npm test && npm run test:panels && npm run test:ui && npm run test:parity && npm run test:offline",
     "doctor": "node doctor.js",
-    "test:panels": "node pm-shell-test.js && node pm-repos-test.js && node pm-initiatives-test.js && node pm-detail-test.js && node pm-tabs-test.js && node pm-term-test.js && node pm-modes-test.js && node pm-r1-test.js && node pm-r2-test.js && node pm-r3-test.js && node pm-r4-test.js && node pm-r5-test.js && node pm-r6-test.js && node pm-r7-test.js && node pm-r8-test.js && node pm-r9-test.js && node pm-r10-test.js && node pm-r11-test.js && node pm-r12-test.js && node pm-r13-test.js && node pm-r14-test.js && node pm-r15-test.js && node pm-r16-test.js && node pm-r17-test.js && node pm-r16-test.js && node pm-r18-test.js && node pm-r19-test.js && node pm-r20-test.js && node pm-r21-test.js && node pm-r22-test.js && node pm-r23-test.js && node pm-r24-test.js",
+    "test:panels": "node pm-shell-test.js && node pm-repos-test.js && node pm-initiatives-test.js && node pm-detail-test.js && node pm-tabs-test.js && node pm-term-test.js && node pm-modes-test.js && node pm-r1-test.js && node pm-r2-test.js && node pm-r3-test.js && node pm-r4-test.js && node pm-r5-test.js && node pm-r6-test.js && node pm-r7-test.js && node pm-r8-test.js && node pm-r9-test.js && node pm-r10-test.js && node pm-r11-test.js && node pm-r12-test.js && node pm-r13-test.js && node pm-r14-test.js && node pm-r15-test.js && node pm-r16-test.js && node pm-r17-test.js && node pm-r16-test.js && node pm-r18-test.js && node pm-r19-test.js && node pm-r20-test.js && node pm-r21-test.js && node pm-r22-test.js && node pm-r23-test.js && node pm-r24-test.js && node pm-r25-test.js",
     "test:offline": "node offline-tarball.test.js"
   },
   "engines": {

package/workspace/public/pm/modes-live.js

@@ -831,7 +831,7 @@ async function tScan() {
 }
 async function tSettings(patch) {
   const out = await post('/api/proactive/settings', patch);
-  reload('today'); reload('brief');
+  reload('today'); reload('brief'); reload('prepare');
   tSay(!out || out.ok === false ? 'bad' : 'ok', !out || out.ok === false ? ((out && out.error) || 'not saved') : 'saved');
 }
 function tCard(c) {
@@ -843,6 +843,7 @@ function tCard(c) {
     el('span', { style: 'display:block;font-size:11px;color:var(--muted-foreground);margin:2px 0 4px' }, iv(c.why + (c.evidence ? ' — ' + c.evidence : ''))),
     el('span', { style: 'display:flex;gap:4px;flex-wrap:wrap' },
       c.open ? b('open', 'open', () => tOpen(c)) : null,
+      c.initiative_id && c.ws ? el('button', { style: BTN, hover: 'color:var(--foreground)', 'data-r23': 'prepare', onClick: () => bgShowPlan(c) }, 'prepare in the background') : null,
       b('useful', 'useful', () => tFeedback({ candidate_id: c.id, verdict: 'useful' }, 'thanks — recorded as useful')),
       b('not useful', 'not-useful', () => tFeedback({ candidate_id: c.id, verdict: 'not-useful' }, 'recorded as not useful')),
       b('wrong priority', 'wrong-priority', () => tFeedback({ candidate_id: c.id, verdict: 'wrong-priority' }, 'recorded as wrong priority')),
@@ -900,6 +901,72 @@ function briefSection() {
   }
   return kids;
 }
+
+/* background preparation (proactive-engine D3): the PM approves one plan; the workspace starts it later, under the same rules as a next-step go */
+let bgPlan = null;            // { cid, state: 'loading'|'ok'|'error', data, error }
+let bgNote = null;
+async function bgShowPlan(c) {
+  if (bgPlan && bgPlan.cid === c.id) { bgPlan = null; setState({}); return; }
+  bgPlan = { cid: c.id, state: 'loading' }; setState({});
+  const out = await post('/api/proactive/prepare/plan', { ws: c.ws, initiative_id: c.initiative_id });
+  bgPlan = !out || out.ok === false ? { cid: c.id, state: 'error', error: (out && out.error) || 'no plan' } : { cid: c.id, state: 'ok', data: out, c };
+  setState({});
+}
+async function bgQueue(c, d) {
+  const out = await post('/api/proactive/prepare/queue', { ws: d.ws, initiative_id: d.initiative_id, item_id: d.item.id, prompt_sha: d.prompt_sha, candidate_id: c.id, confirm: true });
+  bgNote = !out || out.ok === false ? { tone: 'bad', text: (out && out.error) || 'not queued' } : { tone: 'ok', text: 'queued — the workspace starts it when the budget allows' + (d.background.quiet ? ', after quiet hours' : '') + '. It expires in ' + d.background.expire_hours + ' hours.' };
+  if (out && out.ok) bgPlan = null;
+  reload('prepare'); setState({});
+}
+async function bgCancel(e) {
+  const out = await post('/api/proactive/prepare/cancel', { id: e.id });
+  bgNote = !out || out.ok === false ? { tone: 'bad', text: (out && out.error) || 'not cancelled' } : { tone: 'ok', text: 'cancelled' };
+  reload('prepare'); setState({});
+}
+async function bgRun() {
+  const out = await post('/api/proactive/prepare/run', {});
+  bgNote = !out || out.ok === false ? { tone: 'bad', text: (out && out.error) || 'the run failed' }
+    : { tone: 'ok', text: out.results.length ? out.results.map((x) => x.action + (x.reason ? ' (' + x.reason + ')' : '')).join('; ') : 'nothing is queued' };
+  reload('prepare'); setState({});
+}
+function bgPlanView() {
+  if (!bgPlan) return null;
+  if (bgPlan.state === 'loading') return el('div', { style: NOTE, 'data-r23': 'plan-loading' }, iv('reading the plan …'));
+  if (bgPlan.state === 'error') return el('div', { style: NOTE + ';color:var(--destructive)', 'data-r23': 'plan-error' }, iv(bgPlan.error));
+  const d = bgPlan.data; const c = bgPlan.c;
+  const kids = [el('div', { style: 'font-size:12px', 'data-r23': 'plan-step' }, iv('Step: ' + d.item.key + ' — ' + d.item.text))];
+  if (d.refused) { kids.push(el('div', { style: NOTE + ';color:var(--destructive)', 'data-r23': 'plan-refused' }, iv(d.refused.why))); }
+  else {
+    kids.push(el('div', { style: NOTE, 'data-r23': 'plan-where' }, iv(d.plan.why || d.plan.plan)));
+    kids.push(el('div', { style: NOTE, 'data-r23': 'plan-budget' }, iv(d.budget.running + ' of ' + d.budget.limits.concurrent + ' prepared sessions running · ' + d.budget.startedToday + ' of ' + d.budget.limits.perDay + ' started today. The session proposes only: no push, pull request, send, post, acceptance or merge. No outside source and no typed scoring.')));
+    kids.push(el('pre', { 'data-r23': 'plan-prompt', style: 'white-space:pre-wrap;font-family:var(--mono);font-size:10.5px;max-height:140px;overflow:auto;border:1px solid var(--border);padding:6px;margin:4px 0' }, iv(d.prompt)));
+    if (!d.background.enabled) kids.push(el('div', { style: NOTE, 'data-r23': 'plan-off' }, iv('Background prepare is off. Turn it on in the settings below to queue this.')));
+    else kids.push(el('button', { style: BTN + ';color:var(--foreground);border-color:var(--foreground)', hover: 'background:var(--accent)', 'data-r23': 'queue', onClick: () => bgQueue(c, d) }, 'queue it (plan ' + d.prompt_sha + ')'));
+  }
+  return el('div', { 'data-r23': 'plan', style: 'padding:6px 14px 8px;border-bottom:1px solid var(--border)' }, kids);
+}
+function backgroundSection() {
+  const r = read('prepare', '/api/proactive/prepare');
+  const st = status(r, 'the background queue');
+  const kids = [el('div', { style: LABEL }, iv('background preparation'))];
+  if (st) return [...kids, st];
+  const d = r.data;
+  kids.push(el('div', { style: NOTE, 'data-r23': 'bg-state' }, iv((d.enabled ? 'On' : 'Off') + '. ' + d.budget.running + ' of ' + d.budget.limits.concurrent + ' prepared sessions running · ' + d.budget.startedToday + ' of ' + d.budget.limits.perDay + ' started today' + (d.quiet ? ' · quiet hours now' : '') + '. An approval is for one plan and expires in ' + d.expire_hours + ' hours. It runs only while the workspace server runs.')));
+  if (bgNote) kids.push(el('div', { 'data-r23': 'bg-note', style: NOTE + ';color:' + (bgNote.tone === 'bad' ? 'var(--destructive)' : 'var(--foreground)') }, iv(bgNote.text)));
+  if (!d.entries.length) kids.push(el('div', { style: NOTE, 'data-r23': 'bg-empty' }, iv('Nothing has been queued.')));
+  for (const e of d.entries) {
+    kids.push(el('div', { 'data-r23': 'entry', 'data-id': e.id, 'data-status': e.status, style: 'padding:6px 14px;border-bottom:1px solid var(--border)' },
+      el('span', { style: 'display:flex;gap:8px;align-items:baseline' },
+        el('span', { style: 'font-size:12px' }, iv(e.label)),
+        el('span', { style: 'margin-left:auto;font-family:var(--mono);font-size:10px;color:var(--muted-foreground)' }, iv(e.status))),
+      e.reason ? el('span', { style: 'display:block;font-size:11px;color:var(--muted-foreground)', 'data-r23': 'entry-reason' }, iv(e.reason)) : null,
+      el('span', { style: 'display:flex;gap:4px;margin-top:3px' },
+        e.status === 'queued' ? el('button', { style: BTN, hover: 'color:var(--foreground)', 'data-r23': 'cancel', onClick: () => bgCancel(e) }, 'cancel') : null,
+        e.status === 'started' && e.session_id ? el('button', { style: BTN, hover: 'color:var(--foreground)', 'data-r23': 'switch', onClick: async () => { const ini = await import('./panel-initiatives.js'); ini.openTerm(null, { id: e.session_id, name: e.label }); } }, 'switch to it') : null)));
+  }
+  if (d.entries.some((e) => e.status === 'queued')) kids.push(el('div', { style: 'padding:4px 14px' }, el('button', { style: BTN, hover: 'color:var(--foreground)', title: 'look at the queue now; ignores quiet hours only', 'data-r23': 'run', onClick: bgRun }, 'run the queue now')));
+  return kids;
+}
 export function todayList() {
   const r = read('today', '/api/proactive/today');
   const kids = [el('div', { style: NOTE, 'data-r22': 'intro' }, iv('What is waiting for you, worked out from the ledgers and git on this computer. It runs only while the workspace server runs, reads no mail or calendar, and changes nothing: your feedback only changes how this list is ordered later.'))];
@@ -925,7 +992,8 @@ export function todayList() {
   if ((d.unreadable || []).length && !tRetry && typeof setTimeout === 'function') tRetry = setTimeout(() => { tRetry = null; reload('today'); setState({}); }, 4000);
   for (const u of d.unreadable || []) kids.push(el('div', { style: NOTE + ';color:var(--destructive)', 'data-r22': 'unreadable' }, iv('Not read — ' + (u.name || u.repo || 'a repository') + ': ' + (u.error || 'unknown reason') + '. Nothing is shown for it, which is not the same as nothing waiting.')));
   if (d.empty) kids.push(el('div', { style: NOTE, 'data-r22': 'empty' }, iv('Nothing is waiting on any repository that was read.')));
-  for (const c of d.candidates || []) kids.push(tCard(c));
+  for (const c of d.candidates || []) { kids.push(tCard(c)); if (bgPlan && bgPlan.cid === c.id) kids.push(bgPlanView()); }
+  kids.push(...backgroundSection());
   if (d.dismissed) kids.push(el('div', { style: NOTE, 'data-r22': 'dismissed' }, iv(d.dismissed + ' dismissed item(s) hidden for 7 days.')));
   // settings
   kids.push(el('div', { style: LABEL }, iv('settings')));
@@ -933,6 +1001,7 @@ export function todayList() {
     el('input', { type: 'checkbox', checked: on ? 'checked' : null, 'data-r22': attr, onChange: () => tSettings(patch(!on)) }), iv(label));
   kids.push(chk('engine on', s.enabled, 'set-enabled', (v) => ({ enabled: v })));
   for (const t of Object.keys(s.triggers)) kids.push(chk('watch: ' + t, s.triggers[t], 'set-' + t, (v) => ({ triggers: { [t]: v } })));
+  kids.push(chk('background prepare (starts approved sessions by itself)', s.backgroundPrepare, 'set-bg', (v) => ({ backgroundPrepare: v })));
   kids.push(el('div', { style: LABEL }, iv('morning brief')));
   for (const k of Object.keys(s.briefSources || {})) kids.push(chk('read ' + k + (k === 'mail' ? ' (titles and senders only)' : ''), s.briefSources[k], 'set-src-' + k, (v) => ({ briefSources: { [k]: v } })));
   kids.push(chk('typed scoring (sends titles and metadata to the Typesafe service)', s.briefScoring, 'set-scoring', (v) => ({ briefScoring: v })));

package/workspace/server.js

@@ -79,6 +79,7 @@ const sessionBudget = require('./lib/session-budget');
 const judgmentLib = require('./lib/judgment');
 const proactiveLib = require('./lib/proactive');
 const briefLib = require('./lib/brief');
+const prepareQueue = require('./lib/prepare-queue');
 const harness = require('./lib/harness-parse');
 const transcript = require('./lib/transcript-read');
 const skillStore = require('./lib/skill-store');
@@ -2189,7 +2190,7 @@ function checkDueSchedules() {
   return fired;
 }
 // the tick — the persistent server checks on an interval; unref'd so it never blocks exit
-try { const _tick = setInterval(() => { checkDueSchedules(); proactiveTick(); }, 60000); if (_tick.unref) _tick.unref(); } catch {}
+try { const _tick = setInterval(() => { checkDueSchedules(); proactiveTick(); try { prepareTick({ manual: false }); } catch { /* the next tick tries again */ } }, 60000); if (_tick.unref) _tick.unref(); } catch {}
 
 // ── Sessions: real PTYs, owned by the server, with disk-backed scrollback + metadata. ──
 /** @type {Map<string, {id,ws,name,agent,cwd,state,note,created,pty,buf,cols,rows,clients:Set}>} */
@@ -3358,6 +3359,58 @@ 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.' } };
 }
 
+// ── 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
+// hours, with session budget, and while the plan still has the approved hash. Every rule is in lib/prepare-queue.js.
+const PRO_QUEUE = () => path.join(STATE, 'prepare-queue.jsonl');
+function queueEntries() { return prepareQueue.fold(nsRead(PRO_QUEUE())); }
+// The step an agent session may work on now for an initiative: the first `work` step the ladder lets it start.
+function currentWorkItem(w, id) {
+  const got = nextStepsFor(w, id);
+  if (!got.ok) return { ok: false, status: got.status || 500, error: got.error };
+  const item = got.ns.items.find((x) => x.act && x.act.type === 'work' && !nextStepActions.refusal(x, got.ns));
+  if (item) return { ok: true, item };
+  const first = got.ns.items.find((x) => x.first) || got.ns.items[0];
+  const why = first ? nextStepActions.refusal(first, got.ns) : null;
+  return { ok: false, status: 409, error: 'No step is open for an agent session right now' + (why ? ': ' + why.why : '.') };
+}
+function preparePlanFor(w, id, itemId) {
+  return prepareNextStep({ ws: w.id, initiative_id: id, item_id: itemId, agent: 'claude', judgment: false });
+}
+function prepareState() {
+  const settings = proSettings();
+  return { enabled: settings.backgroundPrepare === true, quiet: proactiveLib.inQuietHours(Date.now(), settings.quiet), budget: nsBudget(), max_queued: prepareQueue.MAX_QUEUED, expire_hours: prepareQueue.EXPIRE_MS / 3600000 };
+}
+function prepareTick({ manual = false } = {}) {
+  const out = [];
+  const settings = proSettings();
+  const queued = queueEntries().filter((e) => e.status === 'queued');
+  if (!queued.length) return out;
+  const now = Date.now();
+  const quiet = proactiveLib.inQuietHours(now, settings.quiet);
+  for (const e of queued) {
+    const w = getWs(e.ws);
+    const fresh = w ? preparePlanFor(w, e.initiative_id, e.item_id) : { ok: false, error: 'the repository is no longer registered' };
+    const d = prepareQueue.decide({ entry: e, now, settings, quiet, manual, fresh, budget: nsBudget() });
+    if (d.action === 'wait') { out.push({ id: e.id, action: 'wait', reason: d.reason }); continue; }
+    if (d.action === 'expire' || d.action === 'skip') {
+      nsAppend(PRO_QUEUE(), { id: e.id, at: nowISO(), event: d.action === 'expire' ? 'expired' : 'skipped', reason: d.reason }, 'prepare queue');
+      out.push({ id: e.id, action: d.action, reason: d.reason }); continue;
+    }
+    const started = startWork({ initiative: fresh.initiative_id, ws: fresh.ws, agent: fresh.agent, name: `${fresh.item.key} · ${fresh.initiative_id} (background)`, origin: 'next-step', initialInput: fresh.prompt + '\r' });
+    if (!started.ok) {
+      nsAppend(PRO_QUEUE(), { id: e.id, at: nowISO(), event: 'skipped', reason: 'it could not start — ' + started.error }, 'prepare queue');
+      out.push({ id: e.id, action: 'skip', reason: started.error }); continue;
+    }
+    nsAppend(NS_RUNS(), { id: 'nsr-' + Date.now().toString(36), at: nowISO(), ws: fresh.ws, initiative_id: fresh.initiative_id, item_id: fresh.item.id, key: fresh.item.key, session_id: started.session.id,
+      branch: fresh.plan.branch || null, plan: fresh.plan.plan, prompt_sha: fresh.prompt_sha, judgment: false, profile: null, via: 'background', queue_id: e.id }, 'next-step run');
+    nsAppend(PRO_QUEUE(), { id: e.id, at: nowISO(), event: 'started', session_id: started.session.id }, 'prepare queue');
+    out.push({ id: e.id, action: 'start', session_id: started.session.id });
+  }
+  return out;
+}
+
 // ── Proactive engine, slice D1 (initiative proactive-engine) ─────────────────────────────────────────────────────
 // A scan reads ledgers and git for five conditions and appends each new one to signals.jsonl; Today is computed from what
 // is true now. No model call, no network call, no write into any repository, no session started (lib/proactive.js is
@@ -6221,6 +6274,53 @@ async function handleRequest(req, res) {
     if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
     return json(res, { ok: true, ws: w.id, name: w.name, ...validateLib.readFindings(validationFindingsFile(w)) });
   }
+  /* ── background prepare (D3): plan is read-only; queue records an approval; the runner starts it later ── */
+  if (p === '/api/proactive/prepare/plan' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const id = String(body.initiative_id || '');
+    if (!fourPanel.validId(id)) return json(res, { ok: false, error: 'an initiative id is required' }, 400);
+    const cur = currentWorkItem(w, id);
+    if (!cur.ok) return json(res, { ok: false, error: cur.error }, cur.status || 409);
+    const r = preparePlanFor(w, id, cur.item.id);
+    return json(res, { ...r, background: prepareState() }, r.ok ? 200 : (r.status || 400));
+  }
+  if (p === '/api/proactive/prepare/queue' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const c = prepareQueue.checkRequest(body);
+    if (!c.ok) return json(res, { ok: false, error: c.error }, 400);
+    const why = prepareQueue.canQueue({ settings: proSettings(), entries: queueEntries(), req: c.req });
+    if (why) return json(res, { ok: false, error: why }, 409);
+    const w = getWs(c.req.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const r = preparePlanFor(w, c.req.initiative_id, c.req.item_id);
+    if (!r.ok) return json(res, { ok: false, error: r.error }, r.status || 400);
+    if (r.refused) return json(res, { ok: false, refused: r.refused, error: r.refused.why }, 409);
+    if (r.prompt_sha !== c.req.prompt_sha) return json(res, { ok: false, error: 'the plan changed since you reviewed it — read it again', prompt_sha: r.prompt_sha }, 409);
+    const rec = { id: 'pq-' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5), at: nowISO(), event: 'queued', ws: w.id, initiative_id: c.req.initiative_id, item_id: c.req.item_id, key: r.item.key,
+      candidate_id: c.req.candidate_id, prompt_sha: r.prompt_sha, branch: r.plan.branch || null };
+    const wrote = nsAppend(PRO_QUEUE(), rec, 'prepare queue');
+    if (!wrote.ok) return json(res, { ok: false, error: wrote.error }, 500);
+    return json(res, { ok: true, entry: rec });
+  }
+  if (p === '/api/proactive/prepare/cancel' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const e = queueEntries().find((x) => x.id === String(body.id || ''));
+    if (!e) return json(res, { ok: false, error: 'no such queued entry' }, 404);
+    if (e.status !== 'queued') return json(res, { ok: false, error: `it is already ${e.status} — only a queued entry can be cancelled` }, 409);
+    const wrote = nsAppend(PRO_QUEUE(), { id: e.id, at: nowISO(), event: 'cancelled', reason: 'cancelled by you' }, 'prepare queue');
+    if (!wrote.ok) return json(res, { ok: false, error: wrote.error }, 500);
+    return json(res, { ok: true });
+  }
+  if (p === '/api/proactive/prepare/run' && req.method === 'POST') {
+    // A PM press: look at the queue now. Quiet hours are ignored; the switch, the budget, the plan hash and the 24 hours are not.
+    return json(res, { ok: true, results: prepareTick({ manual: true }) });
+  }
+  if (p === '/api/proactive/prepare' && req.method === 'GET') {
+    const entries = queueEntries().slice(-30).reverse().map((e) => ({ ...e, label: e.key + ' · ' + e.initiative_id }));
+    return json(res, { ok: true, ...prepareState(), entries });
+  }
   /* ── proactive engine (D1): Today is computed, feedback is recorded, nothing is sent, started or changed ── */
   if (p === '/api/proactive/today' && req.method === 'GET') {
     const now = Date.now();