create-pmos 0.166.0 → 0.168.0

package/workspace/lib/driver-run.js

@@ -0,0 +1,187 @@
+'use strict';
+/* driver-run.js — the Initiative Driver's part of the server tick (initiative initiative-driver, PRD sections 1 to 3).
+ *
+ *   create(deps) → { tick(opts), active() }
+ *
+ * server.js builds one driver at start and calls tick() from the 60-second tick. One tick, per repository (the lead tree of each):
+ *   1. writes the ledger's `epoch` on the first scan, so only events AFTER it wake a run (an old initiative is history);
+ *   2. closes runs that were alive when the server stopped (`run-end`, reason "interrupted"): they still count against the day;
+ *   3. finds the wakes: a `created` placement line (the page, Triage accept and `pmos initiative new` all write one), a board
+ *      `move` line, a proposal the PM sent back with a note. Each key wakes once (the ledger's `wake` line makes it idempotent);
+ *   4. every 30 minutes inside the day-check window, and outside quiet hours, runs the unblock sweep (no model, lib/driver.js);
+ *   5. starts the queued runs the rules allow (mode, pause, budget, 3 at once) through spawnSession with origin `drive:<kind>:<id>`
+ *      and the skill prompt, which lib/headless.js turns into a `claude -p` run with a fixed tool list.
+ * `PMOS_DRIVER=off` does none of it. A run ends in a `run-end` line with its reason when it fails or times out.
+ *
+ * deps: { gather?(w, ctx, opts) → facts answer (tests), workspaces() → [w], isLead(w), stateDirFor(w), ctx (for lib/routes-boards.js), runtimeDir, settings() → proactive settings,
+ *         inQuiet(now, quiet) → bool, spawn(spec) → session row, promptFor(kind) → skill body | null, boardOf(w, id) → board id | null,
+ *         homeId() → the workspace id that holds the Work tasks, headlessOff() → bool, env, warn(what, err) }
+ * `spawn(spec)` gets { name, ws, origin, initialInput, initiative, onDone }; it returns the session row ({ id, state, headless }).
+ */
+const fs = require('fs');
+const path = require('path');
+const D = require('./driver.js');
+const facts = require('./driver-facts.js');
+const proactive = require('./proactive.js');
+
+const off = (env) => /^(off|0|false|no)$/i.test(String((env || process.env).PMOS_DRIVER || '').trim());
+const hhmm = (ms) => { const d = new Date(ms); return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`; };
+const dayCheckOpen = (settings, now, inQuiet) => {
+  const dc = (settings && settings.dayCheck) || proactive.DEFAULTS.dayCheck;
+  const t = hhmm(now);
+  return settings && settings.enabled === false ? false : (t >= dc.start && t < dc.end && !inQuiet(now, settings && settings.quiet));
+};
+
+/** The lines of a plain JSONL file that parse; a missing file is empty. */
+function readJsonl(f) {
+  let text = '';
+  try { text = fs.readFileSync(f, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const raw of text.split('\n')) { if (!raw.trim()) continue; try { const l = JSON.parse(raw); if (l && typeof l === 'object') out.push(l); } catch { /* torn line */ } }
+  return out;
+}
+
+function create(deps) {
+  const active = new Map();     // run id → { target, ledger, session }
+  const lastSweep = new Map();  // ledger file → ms
+  const warn = deps.warn || (() => {});
+  const gather = deps.gather || facts.gather;   // tests pass their own facts
+
+  function readState(file) { return D.fold(D.readLines(file)); }
+
+  function describe(w, target, wakeLines, state, factsNow) {
+    const lines = [];
+    const reasons = [...new Set(wakeLines.map((x) => x.reason))];
+    let title = target.id; let stage = null; let facts1 = null;
+    if (factsNow) {
+      facts1 = target.kind === 'work' ? factsNow.work.find((x) => x.id === target.id) : factsNow.initiatives.find((x) => x.id === target.id);
+      if (facts1 && facts1.title) title = facts1.title;
+    }
+    lines.push(target.kind === 'work'
+      ? `Target: Work task ${target.id} "${title}" (workspace id ${target.ws}). Skill: work-unblock.`
+      : `Target: initiative ${target.id} "${title}" in repository ${w.name || path.basename(w.root)} (workspace id ${target.ws}). Skill: initiative-drive.`);
+    lines.push(`Why this run started: ${reasons.join(', ')}.`);
+    if (facts1 && target.kind === 'initiative') {
+      stage = facts1.cat;
+      lines.push(`Stage category: ${stage || 'unknown'}. Kept problem statement: ${facts1.has_problem ? 'yes' : 'no'}. Kept evidence: ${facts1.has_evidence ? 'yes' : 'no'}. PRD: ${facts1.has_prd ? 'yes' : 'no'}. Anchor: ${facts1.has_anchor ? 'yes' : 'no'}.`);
+    }
+    if (facts1 && target.kind === 'work') {
+      lines.push(`Placement: ${facts1.placement}. Due: ${facts1.due || 'none'}. Waiting on: ${facts1.waiting_on || 'nobody'}${facts1.waiting_since ? ` since ${String(facts1.waiting_since).slice(0, 10)}` : ''}. Steps: ${facts1.steps}.`);
+    }
+    const blockers = wakeLines.filter((x) => x.blocker).map((x) => x.blocker);
+    if (blockers.length) lines.push(`Blockers the sweep found: ${[...new Set(blockers)].join(', ')}.`);
+    const retNotes = wakeLines.filter((x) => x.reason === 'answered').map((x) => state.proposals.get(String(x.key).replace(/^answered:/, ''))).filter(Boolean);
+    for (const p of retNotes) lines.push(`The PM sent back ${p.id} (${p.what}) with this note: "${p.note}". Revise it and file a new proposal.`);
+    const mine = [...state.proposals.values()].filter((p) => D.targetKey(p.target) === D.targetKey(target));
+    if (mine.length) lines.push(`Proposals so far: ${mine.map((p) => `${p.id} ${p.what} (${p.state})`).join('; ')}. Do not file one again.`);
+    return lines;
+  }
+
+  function startRun(w, file, group, state, factsNow, now) {
+    const kind = group.target.kind;
+    const skill = deps.promptFor(kind === 'work' ? 'work-unblock' : 'initiative-drive');
+    const runId = D.newId('run');
+    const wakeLines = state.wakes.filter((x) => group.wakes.includes(x.key));
+    const board = group.board || null;
+    if (!skill) {
+      D.append(file, { ev: 'run-start', run: runId, target: group.target, board, wakes: group.wakes, session: null }, { now });
+      D.append(file, { ev: 'run-end', run: runId, ok: false, reason: `the ${kind === 'work' ? 'work-unblock' : 'initiative-drive'} skill is not installed`, agent_run: agentRun(runId, group.target, false, now) }, { now });
+      return;
+    }
+    const prompt = `${skill}\n\nThis run:\n${describe(w, group.target, wakeLines, state, factsNow).map((l) => '- ' + l).join('\n')}\n\nFile every result with \`pmos driver propose\`. Send nothing, edit nothing.`;
+    let session = null;
+    try {
+      session = deps.spawn({
+        name: `Driver · ${kind} ${group.target.id}`, ws: w.id, origin: `drive:${kind}:${group.target.id}`, initialInput: prompt + '\r',
+        initiative: kind === 'initiative' ? group.target.id : undefined,
+        onDone: (r) => endRun(file, runId, group.target, r),
+      });
+    } catch (e) { warn('driver run', e); }
+    D.append(file, { ev: 'run-start', run: runId, target: group.target, board, wakes: group.wakes, session: session ? session.id : null }, { now });
+    if (!session || session.state === 'exited' || session.headless !== 'drive') {
+      // A start that did not become a headless run (no `claude` on the PATH, a refused model choice, a pane because headless
+      // is off) is a failed run. It counts against the day, as every failed run does. Never leave a driver in a pane.
+      if (session && session.headless !== 'drive' && session.state !== 'exited' && deps.stop) { try { deps.stop(session); } catch { /* best effort */ } }
+      D.append(file, { ev: 'run-end', run: runId, ok: false, reason: (session && session.note) || 'the run could not start as a background run', agent_run: agentRun(runId, group.target, false, now) }, { now });
+      return;
+    }
+    active.set(runId, { target: group.target, ledger: file, session: session.id });
+  }
+
+  const agentRun = (runId, target, ok, now) => ({ run_id: runId, initiative_id: target.kind === 'initiative' ? target.id : null, kind: 'driver', target_kind: target.kind,
+    ok, human_corrections: 0, builder_model: 'not recorded in the repo', created_at: new Date(now == null ? Date.now() : now).toISOString() });
+
+  function endRun(file, runId, target, r) {
+    active.delete(runId);
+    const res = (r && r.result) || {};
+    const ok = !!(r && !r.timedOut && !r.stopped && r.code === 0 && res.ok && !res.isError);
+    const reason = ok ? null : (r && r.note) || 'the run failed';
+    try {
+      D.append(file, { ev: 'run-end', run: runId, ok, ...(reason ? { reason } : {}), ...(res.denied && res.denied.length ? { denied: res.denied } : {}),
+        agent_run: agentRun(runId, target, ok) });
+    } catch (e) { warn('driver run end', e); }
+  }
+
+  function tick({ now = Date.now(), env } = {}) {
+    if (off(env || deps.env)) return { off: true };
+    const summary = { epoch: 0, woke: 0, swept: 0, started: 0, refused: 0 };
+    const leads = [];
+    for (const w of deps.workspaces()) {
+      let dir = null;
+      try { dir = deps.isLead(w) ? deps.stateDirFor(w) : null; } catch { dir = null; }
+      if (dir) leads.push({ w, file: D.ledgerFile(dir), dir });
+    }
+    const settings = deps.settings();
+    const home = deps.homeId();
+    for (const { w, file, dir } of leads) {
+      try {
+        let state = readState(file);
+        if (!state.epoch) { D.append(file, { ev: 'epoch' }, { now }); state = readState(file); summary.epoch++; }
+        // Runs that were alive when the server stopped are over; they keep their place in the day's count.
+        for (const r of state.runs.values()) {
+          if (!r.end && !active.has(r.run)) D.append(file, { ev: 'run-end', run: r.run, ok: false, reason: 'interrupted: the workspace restarted', agent_run: agentRun(r.run, r.target, false, now) }, { now });
+        }
+        const boardOf = (id) => { try { return deps.boardOf(w, id); } catch { return null; } };
+        let created = [];
+        try { created = require('./plan-ledgers.js').readLines(w.root, 'placements').lines.map((x) => x.rec).filter((r) => r && r.ev === 'created'); } catch { created = []; }
+        const moved = readJsonl(path.join(dir, 'boards.jsonl')).filter((e) => e.kind === 'move');
+        const newWakes = [...D.wakesFromLedgers({ created, moved }, state, { ws: w.id, epoch: state.epoch, boardOf }), ...D.answeredWakes(state, { boardOf })];
+        for (const l of newWakes) { D.append(file, l, { now }); summary.woke++; }
+        state = readState(file);
+        // The unblock sweep: deterministic, every 30 minutes inside the day-check window.
+        const due = !lastSweep.has(file) || now - lastSweep.get(file) >= D.SWEEP_EVERY_MS;
+        let factsNow = null;
+        if (due && dayCheckOpen(settings, now, deps.inQuiet)) {
+          const g = gather(w, deps.ctx, { now, includeWork: w.id === home, runtimeDir: deps.runtimeDir, driverState: state });
+          if (g.ok) {
+            factsNow = g.facts;
+            lastSweep.set(file, now);
+            const sw = D.sweepLines(g.facts, state, { now, stalledDays: settings.stalledDays });
+            for (const l of sw.lines) { D.append(file, l, { now }); if (l.ev === 'wake') summary.swept++; }
+            state = readState(file);
+          } else if (!g.pending) warn('driver sweep', new Error(g.error));
+        }
+        // Start what the rules allow.
+        if (deps.headlessOff()) continue;   // a driver never runs in a pane
+        const running = [...active.values()];
+        const p = D.plan(state, { now, running: active.size, activeTargets: running.map((r) => D.targetKey(r.target)) });
+        for (const r of p.refused) { D.append(file, { ev: 'refused', target: r.target, wakes: r.wakes, reason: r.reason }, { now }); summary.refused++; }
+        if (p.start.length && !factsNow) {
+          const g = gather(w, deps.ctx, { now, includeWork: w.id === home, runtimeDir: deps.runtimeDir, driverState: state });
+          factsNow = g.ok ? g.facts : null;
+        }
+        let live = active.size;
+        for (const group of p.start) {
+          if (live >= D.BUDGET.concurrent) break;
+          startRun(w, file, group, state, factsNow, now);
+          live = active.size; summary.started++;
+        }
+      } catch (e) { warn('driver tick', e); }
+    }
+    return summary;
+  }
+
+  return { tick, active: () => [...active.keys()] };
+}
+
+module.exports = { create, off, dayCheckOpen };

package/workspace/lib/driver.js

@@ -0,0 +1,408 @@
+'use strict';
+/* driver.js — the Initiative Driver's ledger and rules (initiative initiative-driver, PRD sections 1 to 5).
+ *
+ * The driver is a short headless run for one initiative or one Work task. It reads the record, files what it found as
+ * PROPOSALS, and ends. The PM keeps, sends back or drops each proposal. This file is the pure core: the shape of every
+ * line in <state folder>/driver.jsonl, the fold, the budget, the modes, the wake queue and the unblock sweep. It reads the
+ * clock only through the `now` its callers pass. The only I/O is the thin read/append pair at the bottom.
+ *
+ *   LEDGER · KINDS · WHATS · MODES · DEFAULT_MODE · WAKES · BUDGET
+ *   stateDirOf(root, { create })        → the repository's state folder (pmos/state, state or .pmos), else null
+ *   ledgerFile(stateDir)                → <state folder>/driver.jsonl
+ *   append(file, line, { now })         → the line written. THE SINGLE WRITER of driver.jsonl.
+ *   readLines(file)                     → every line that parses, in file order
+ *   checkProposal(input)                → { ok, proposal } | { ok: false, error }   the shape of one proposal
+ *   fold(lines)                         → the current state (proposals, decisions, runs, wakes, pauses, modes, blockers)
+ *   modeOf(state, board) · isPaused(state, target) · openProposals(state, target?)
+ *   admit(state, { target, board }, { now, running }) → { ok } | { ok: false, refuse: reason } | { ok: false, wait: reason }
+ *   plan(state, { now, running })       → { start: [{ target, board, wakes[] }], refused: [{ target, wakes[], reason }] }
+ *   detect(facts, state, { now, stalledDays }) → the blockers, each { key, target, board, title, code, owner, cat, text }
+ *   sweepLines(facts, state, { now, stalledDays }) → { blockers, lines } the lines to append (once per blocker per day)
+ *   wakesFromLedgers({ created, moved }, state, { ws, epoch }) → wake lines for creations and moves not yet woken
+ *   answeredWakes(state)                → wake lines for proposals the PM sent back with a note
+ *   localDay(ms) · targetKey(target) · wsIdOf(root)
+ *
+ * THE LINES. Every line is { v: 1, ev, …, at }. Who wrote a decision is the call path (lib/actor.js), never a field:
+ *   proposal   { id, target: { kind, ws, id }, what, data, why, sources: [{ label, ref }], run, by }   by an agent session
+ *   keep|return|drop  { proposal, note?, by }           PM only: the fold ignores one whose `by` is not pm:*
+ *   correction { proposal, run, kind: 'return'|'drop', by }   one per return or drop; the north star counts it
+ *   pause|resume { target, by } · mode { board, mode, by }     PM only, as above. `board` '*' is every board.
+ *   wake       { key, target, board, reason: created|moved|answered|stuck, blocker? }   queued: a run should start
+ *   run-start  { run, target, board, wakes: [key], session }   one per run; counts against the day's budget
+ *   run-end    { run, ok, reason?, agent_run }                  agent_run is the run record the correction rate reads
+ *   refused    { target, wakes: [key], reason }                 a wake the rules turned away, recorded
+ *   blocker    { key, day, target, board, code, owner: 'pm'|'agent', text }   the sweep's finding, once per key per day
+ *   epoch      { }                                              the first scan of this ledger: older events do not wake
+ *
+ * BUDGET (PM decision 4): 3 runs per initiative per local day, 1 per Work task per day, 3 at once, no daily total. A run
+ * that fails or times out still counts. A wake the budget turns away is recorded as `refused`; a wake that only waits for
+ * a free slot stays queued. Several wakes of one target are answered by ONE run.
+ *
+ * THE FACTORY NEVER WRITES HERE (D65): the CLI and the routes pass the actor from the call path. This ledger is not an
+ * initiative record, an acceptance, an anchor or a stage move; Keep writes those through their own writers.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const LEDGER = 'driver.jsonl';
+const KINDS = Object.freeze(['initiative', 'work']);
+const WHATS = Object.freeze({
+  initiative: Object.freeze(['problem', 'evidence', 'sizing', 'assumption', 'stakeholders', 'move', 'note']),
+  work: Object.freeze(['next-step', 'follow-up', 'note']),
+});
+// A claim without a pointer is not a proposal (PRD section 2: "Nothing without a pointer").
+const NEEDS_SOURCE = Object.freeze(['evidence', 'sizing', 'assumption', 'stakeholders']);
+const MODES = Object.freeze(['off', 'shadow', 'approve']);
+const DEFAULT_MODE = 'approve';
+const WAKES = Object.freeze(['created', 'moved', 'answered', 'stuck']);
+const EVENTS = Object.freeze(['proposal', 'keep', 'return', 'drop', 'correction', 'pause', 'resume', 'mode', 'wake', 'run-start', 'run-end', 'refused', 'blocker', 'epoch']);
+const BUDGET = Object.freeze({ initiativePerDay: 3, workPerDay: 1, concurrent: 3 });
+const DAY = 86400000;
+const PM_WAIT_MS = DAY;                 // an open proposal older than this makes the PM the blocker
+const SWEEP_EVERY_MS = 30 * 60 * 1000;  // the sweep's cadence inside the day-check window
+const DEFAULT_STALLED_DAYS = 5;
+const WORK_WAIT_DAYS = 3;
+const WORK_UNTOUCHED_DAYS = 7;          // lib/pm-items.js REVIEW_DAYS
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
+const WS_RE = /^[A-Za-z0-9._-]{1,80}$/;
+const PROPOSAL_RE = /^p-[0-9a-f]{10}$/;
+const RUN_RE = /^run-[0-9a-f]{10}$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const MAX_DATA = 8000;
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const oneLine = (v, max) => typeof v === 'string' && v.trim().length >= 1 && v.trim().length <= max && !/[\r\n\x00-\x08\x0b-\x1f]/.test(v);
+const pm = (by) => typeof by === 'string' && by.startsWith('pm:');
+
+const targetKey = (t) => `${t.kind}:${t.ws}:${t.id}`;
+const wsIdOf = (root) => crypto.createHash('sha1').update(path.resolve(root)).digest('hex').slice(0, 10);
+/** The local calendar day of a time in ms, YYYY-MM-DD. The budget counts per local day. */
+function localDay(ms) {
+  const d = new Date(ms);
+  const p = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+// ── where the ledger lives ───────────────────────────────────────────────────────────────────────────
+const isDir = (d) => { try { return fs.statSync(d).isDirectory(); } catch { return false; } };
+/** The repository's state folder, by the rule server.js stateDirFor uses; the checkout this file ships in falls back to
+ * workspace/state, as the server does for PMOS-self. Null when there is none (and `create` is off). */
+function stateDirOf(root, { create = false } = {}) {
+  if (!root) return null;
+  for (const rel of [['pmos', 'state'], ['state'], ['.pmos']]) {
+    const d = path.join(root, ...rel);
+    if (isDir(d)) return d;
+  }
+  if (path.resolve(root) === path.resolve(__dirname, '..', '..') && isDir(path.join(__dirname, '..', 'state'))) return path.join(__dirname, '..', 'state');
+  if (create) {
+    const d = path.join(root, 'pmos', 'state');
+    try { fs.mkdirSync(d, { recursive: true }); return d; } catch { return null; }
+  }
+  return null;
+}
+const ledgerFile = (stateDir) => (stateDir ? path.join(stateDir, LEDGER) : null);
+
+// ── the one writer, and the read ─────────────────────────────────────────────────────────────────────
+/** THE SINGLE WRITER of driver.jsonl. `v` and `at` are set here; a caller never chooses them. */
+function append(file, line, { now } = {}) {
+  if (!file) throw new Error('driver: no ledger file');
+  if (!isObj(line) || !EVENTS.includes(line.ev)) throw new Error(`driver: unknown event ${JSON.stringify(line && line.ev)}`);
+  const out = { ...line, v: 1, at: new Date(now == null ? Date.now() : now).toISOString() };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(out) + '\n');
+  return out;
+}
+function readLines(file) {
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const raw of text.split('\n')) {
+    if (!raw.trim()) continue;
+    try { const l = JSON.parse(raw); if (isObj(l) && EVENTS.includes(l.ev)) out.push(l); } catch { /* a torn line is skipped */ }
+  }
+  return out;
+}
+const newId = (prefix) => `${prefix}-${crypto.randomBytes(5).toString('hex')}`;
+
+// ── a proposal ───────────────────────────────────────────────────────────────────────────────────────
+function checkTarget(t) {
+  if (!isObj(t)) return { ok: false, error: 'target must be { kind, ws, id }' };
+  if (!KINDS.includes(t.kind)) return { ok: false, error: `target kind must be one of ${KINDS.join(', ')}` };
+  if (typeof t.ws !== 'string' || !WS_RE.test(t.ws)) return { ok: false, error: 'target ws must be a workspace id' };
+  if (typeof t.id !== 'string' || !ID_RE.test(t.id)) return { ok: false, error: 'target id must be an initiative or Work task id (letters, digits, . _ -)' };
+  return { ok: true, target: { kind: t.kind, ws: t.ws, id: t.id } };
+}
+
+/** The shape of one proposal as an agent files it. Returns the line fields the writer adds `id`, `run`, `by` to. */
+function checkProposal(input) {
+  const i = isObj(input) ? input : {};
+  const t = checkTarget({ kind: i.kind, ws: i.ws, id: i.id });
+  if (!t.ok) return t;
+  if (!WHATS[t.target.kind].includes(i.what)) return { ok: false, error: `what must be one of ${WHATS[t.target.kind].join(', ')} for ${t.target.kind === 'work' ? 'a Work task' : 'an initiative'}` };
+  if (!oneLine(i.why, 500)) return { ok: false, error: 'why is one line of 1 to 500 characters' };
+  let data = i.data;
+  if (typeof data === 'string') data = { text: data };
+  if (!isObj(data)) return { ok: false, error: 'data must be an object or text' };
+  if (JSON.stringify(data).length > MAX_DATA) return { ok: false, error: `data is too long (at most ${MAX_DATA} characters)` };
+  const sources = [];
+  if (i.sources !== undefined && i.sources !== null) {
+    if (!Array.isArray(i.sources) || i.sources.length > 20) return { ok: false, error: 'sources is a list of at most 20 { label, ref }' };
+    for (const s of i.sources) {
+      if (!isObj(s) || !oneLine(s.label, 80) || !oneLine(s.ref, 500)) return { ok: false, error: 'each source needs a label (up to 80 characters) and a ref (a Jira key, link or path, up to 500)' };
+      sources.push({ label: s.label.trim(), ref: s.ref.trim() });
+    }
+  }
+  if (NEEDS_SOURCE.includes(i.what) && !sources.length) return { ok: false, error: `${/^[aeiou]/.test(i.what) ? 'an' : 'a'} ${i.what} proposal needs at least one source with a pointer (--source label=ref); nothing without a pointer` };
+  if (i.what === 'evidence' && Array.isArray(data.items) && data.items.some((x) => !isObj(x) || !oneLine(x.text, 500) || !oneLine(x.ref, 500))) {
+    return { ok: false, error: 'every evidence item needs text and a ref (the pointer to where you read it)' };
+  }
+  if (i.what === 'problem') {
+    const c = require('./stage-tools.js').checkData('problem', { text: data.text });
+    if (!c.ok) return { ok: false, error: c.error };
+    data = { text: c.data.text };
+  } else if (i.what === 'move') {
+    if (!oneLine(data.to, 120)) return { ok: false, error: 'a move needs data.to: the name of the stage' };
+    data = { to: data.to.trim(), ...(oneLine(data.board, 120) ? { board: data.board.trim() } : {}) };
+  } else if (i.what === 'next-step') {
+    if (!oneLine(data.text, 500)) return { ok: false, error: 'a next step needs data.text: one line of up to 500 characters' };
+    if (data.due != null && !(typeof data.due === 'string' && DATE_RE.test(data.due))) return { ok: false, error: 'data.due is YYYY-MM-DD' };
+    data = { text: data.text.trim(), ...(data.due ? { due: data.due } : {}) };
+  }
+  return { ok: true, proposal: { target: t.target, what: i.what, data, why: i.why.trim(), sources } };
+}
+
+// ── the fold ─────────────────────────────────────────────────────────────────────────────────────────
+function emptyState() {
+  return { epoch: null, proposals: new Map(), order: [], paused: new Map(), modes: new Map(), runs: new Map(), bySession: new Map(),
+    wakes: [], wakeKeys: new Set(), blockers: [], blockerDays: new Set(), refusals: [], corrections: [] };
+}
+
+/** The current state of one ledger. Order matters only inside a kind; a decision line from anything but the PM is ignored. */
+function fold(lines) {
+  const s = emptyState();
+  const wakeBy = new Map();
+  for (const l of lines || []) {
+    if (!isObj(l)) continue;
+    switch (l.ev) {
+      case 'epoch': if (!s.epoch) s.epoch = l.at || null; break;
+      case 'proposal': {
+        if (!PROPOSAL_RE.test(String(l.id)) || s.proposals.has(l.id) || !checkTarget(l.target).ok) break;
+        s.proposals.set(l.id, { id: l.id, target: { kind: l.target.kind, ws: l.target.ws, id: l.target.id }, what: l.what, data: l.data, why: l.why,
+          sources: Array.isArray(l.sources) ? l.sources : [], run: l.run || null, by: l.by || null, at: l.at || null, state: 'open', note: null, decided_at: null, decided_by: null });
+        s.order.push(l.id);
+        break;
+      }
+      case 'keep': case 'return': case 'drop': {
+        const p = s.proposals.get(l.proposal);
+        if (!p || p.state !== 'open' || !pm(l.by)) break;
+        p.state = l.ev === 'keep' ? 'kept' : l.ev === 'return' ? 'returned' : 'dropped';
+        p.note = typeof l.note === 'string' && l.note ? l.note : null; p.decided_at = l.at || null; p.decided_by = l.by;
+        break;
+      }
+      case 'correction': s.corrections.push({ proposal: l.proposal || null, run: l.run || null, kind: l.kind, at: l.at || null }); break;
+      case 'pause': case 'resume': if (pm(l.by) && checkTarget(l.target).ok) s.paused.set(targetKey(l.target), l.ev === 'pause'); break;
+      case 'mode': if (pm(l.by) && MODES.includes(l.mode) && typeof l.board === 'string' && l.board) s.modes.set(l.board, l.mode); break;
+      case 'wake': {
+        if (typeof l.key !== 'string' || s.wakeKeys.has(l.key) || !checkTarget(l.target).ok) break;
+        s.wakeKeys.add(l.key);
+        const w = { key: l.key, target: l.target, board: l.board || null, reason: l.reason, blocker: l.blocker || null, at: l.at || null, state: 'queued' };
+        s.wakes.push(w); wakeBy.set(l.key, w);
+        break;
+      }
+      case 'run-start': {
+        if (typeof l.run !== 'string' || s.runs.has(l.run) || !checkTarget(l.target).ok) break;
+        const r = { run: l.run, target: l.target, board: l.board || null, wakes: Array.isArray(l.wakes) ? l.wakes : [], session: l.session || null, start: l.at || null, end: null, ok: null, reason: null, agent_run: null };
+        s.runs.set(l.run, r);
+        if (r.session) s.bySession.set(String(r.session).replace(/\.[0-9a-f]{8}$/, ''), l.run);
+        for (const k of r.wakes) { const w = wakeBy.get(k); if (w) w.state = 'started'; }
+        break;
+      }
+      case 'run-end': {
+        const r = s.runs.get(l.run);
+        if (!r || r.end) break;
+        r.end = l.at || null; r.ok = l.ok === true; r.reason = typeof l.reason === 'string' ? l.reason : null; r.agent_run = isObj(l.agent_run) ? l.agent_run : null;
+        break;
+      }
+      case 'refused': {
+        s.refusals.push({ target: l.target, wakes: l.wakes || [], reason: l.reason, at: l.at || null });
+        for (const k of l.wakes || []) { const w = wakeBy.get(k); if (w) w.state = 'refused'; }
+        break;
+      }
+      case 'blocker': if (typeof l.key === 'string' && typeof l.day === 'string') { s.blockers.push(l); s.blockerDays.add(`${l.key}|${l.day}`); } break;
+      default: break;
+    }
+  }
+  return s;
+}
+
+const modeOf = (state, board) => (board && state.modes.get(board)) || state.modes.get('*') || DEFAULT_MODE;
+const isPaused = (state, target) => state.paused.get(targetKey(target)) === true;
+function openProposals(state, target) {
+  const want = target ? targetKey(target) : null;
+  return state.order.map((id) => state.proposals.get(id)).filter((p) => p.state === 'open' && (!want || targetKey(p.target) === want));
+}
+const runsOnDay = (state, target, day) => [...state.runs.values()].filter((r) => targetKey(r.target) === targetKey(target) && r.start && localDay(Date.parse(r.start)) === day).length;
+const budgetFor = (target) => (target.kind === 'work' ? BUDGET.workPerDay : BUDGET.initiativePerDay);
+
+/** May a run start for this target now? `running` is the number of driver runs alive. A closed rule refuses (and the
+ * caller records it); a full house only waits. */
+function admit(state, { target, board }, { now, running = 0 } = {}) {
+  if (modeOf(state, board) === 'off') return { ok: false, refuse: 'mode-off' };
+  if (isPaused(state, target)) return { ok: false, refuse: 'paused' };
+  if (runsOnDay(state, target, localDay(now)) >= budgetFor(target)) return { ok: false, refuse: 'budget' };
+  if (running >= BUDGET.concurrent) return { ok: false, wait: 'concurrency' };
+  return { ok: true };
+}
+
+/** What to do with the queued wakes now. Wakes of one target are answered by one run. `running` counts the runs alive;
+ * `activeTargets` (target keys) holds the targets that have one, so a target never has two at once. */
+function plan(state, { now, running = 0, activeTargets = [] } = {}) {
+  const groups = new Map();
+  for (const w of state.wakes) {
+    if (w.state !== 'queued') continue;
+    const k = targetKey(w.target);
+    if (!groups.has(k)) groups.set(k, { target: w.target, board: w.board, wakes: [] });
+    groups.get(k).wakes.push(w.key);
+  }
+  const start = []; const refused = [];
+  const active = new Set(activeTargets);
+  // Plan on a scratch copy of the run counts so four wakes of one target never plan four runs.
+  const planned = new Map();
+  let live = running;
+  for (const g of groups.values()) {
+    if (active.has(targetKey(g.target))) continue;
+    const verdict = admit(state, g, { now, running: live });
+    if (verdict.refuse) { refused.push({ target: g.target, wakes: g.wakes, reason: verdict.refuse }); continue; }
+    if (verdict.wait) continue;
+    const day = localDay(now);
+    const used = runsOnDay(state, g.target, day) + (planned.get(targetKey(g.target)) || 0);
+    if (used >= budgetFor(g.target)) { refused.push({ target: g.target, wakes: g.wakes, reason: 'budget' }); continue; }
+    planned.set(targetKey(g.target), (planned.get(targetKey(g.target)) || 0) + 1);
+    live++;
+    start.push(g);
+  }
+  return { start, refused };
+}
+
+// ── the unblock sweep ────────────────────────────────────────────────────────────────────────────────
+/* FACTS (the server gathers them; this file never reads a repository):
+ *   facts.day            'YYYY-MM-DD', local                    facts.now   ms
+ *   facts.initiatives[]  { ws, board, id, title, cat: Discover|Plan|Do|Learn, active, last_activity (ms|null),
+ *                          has_problem, has_evidence, has_prd, has_done_criteria, has_anchor,
+ *                          has_tickets, last_ticket_move (ms|null), blocked_tickets: [key], check_by ('YYYY-MM-DD'|null),
+ *                          outcome_checked, kill_tripped }
+ *   facts.work[]         { ws, id, title, done, placement: inbox|today|upcoming|waiting|someday, due, waiting_on, waiting_since (ISO|null),
+ *                          touched_at (ISO|null), untouched (bool: the Review queue holds it), steps (count) }
+ * A blocker is { key, target, board, title, code, owner: 'pm'|'agent', cat, text }. */
+const iniKey = (i, code) => `initiative:${i.ws}:${i.id}:${code}`;
+const workKey = (w, code) => `work:${w.ws}:${w.id}:${code}`;
+
+function detect(facts, state, { now, stalledDays } = {}) {
+  const t = now == null ? facts.now : now;
+  const day = facts.day || localDay(t);
+  const stall = (stalledDays || DEFAULT_STALLED_DAYS) * DAY;
+  const out = [];
+  const add = (target, board, title, code, owner, cat, text, key) => out.push({ key, target, board, title, code, owner, cat: cat || null, text });
+  for (const i of facts.initiatives || []) {
+    if (!i || !i.active) continue;
+    const target = { kind: 'initiative', ws: i.ws, id: i.id };
+    const title = i.title || i.id;
+    const b = (code, owner, cat, text) => add(target, i.board || null, title, code, owner, cat, text, iniKey(i, code));
+    const oldest = openProposals(state, target).filter((p) => p.at && t - Date.parse(p.at) >= PM_WAIT_MS).sort((a, c) => Date.parse(a.at) - Date.parse(c.at))[0];
+    if (oldest) b('pm-open', 'pm', null, `The agent's drafts have waited on you since ${oldest.at.slice(0, 10)}`);
+    if (i.cat === 'Discover') {
+      if (!i.has_problem) b('no-problem', 'agent', 'Discover', 'No kept problem statement');
+      if (!i.has_evidence) b('no-evidence', 'agent', 'Discover', 'No evidence is kept');
+    } else if (i.cat === 'Plan') {
+      if (!i.has_prd) b('no-prd', 'agent', 'Plan', 'No PRD');
+      if (!i.has_done_criteria) b('no-done-criteria', 'agent', 'Plan', 'No done-criteria');
+      if (!i.has_anchor) b('no-anchor', 'agent', 'Plan', 'No anchor (a KR or a health budget)');
+    } else if (i.cat === 'Do') {
+      if (i.has_tickets && i.last_ticket_move != null && t - i.last_ticket_move >= stall) b('no-ticket-movement', 'agent', 'Do', `No Jira ticket moved for ${Math.floor((t - i.last_ticket_move) / DAY)} days`);
+      if (Array.isArray(i.blocked_tickets) && i.blocked_tickets.length) b('ticket-blocked', 'agent', 'Do', `Blocked ticket: ${i.blocked_tickets.join(', ')}`);
+    } else if (i.cat === 'Learn') {
+      if (i.check_by && i.check_by < day && !i.outcome_checked) b('check-by-passed', 'agent', 'Learn', `The check-by date ${i.check_by} passed with no outcome check`);
+      if (i.kill_tripped) b('kill-tripped', 'agent', 'Learn', 'A kill condition tripped');
+    }
+    if (i.last_activity != null && t - i.last_activity >= stall) b('stalled', 'agent', null, `Nothing changed for ${Math.floor((t - i.last_activity) / DAY)} days`);
+  }
+  for (const w of facts.work || []) {
+    if (!w || w.done) continue;
+    const target = { kind: 'work', ws: w.ws, id: w.id };
+    const title = w.title || w.id;
+    const b = (code, owner, text) => add(target, 'work', title, code, owner, null, text, workKey(w, code));
+    const oldest = openProposals(state, target).filter((p) => p.at && t - Date.parse(p.at) >= PM_WAIT_MS).sort((a, c) => Date.parse(a.at) - Date.parse(c.at))[0];
+    if (oldest) b('pm-open', 'pm', `The agent's drafts have waited on you since ${oldest.at.slice(0, 10)}`);
+    if (w.due && w.due < day) b('work-overdue', 'agent', `Overdue since ${w.due}`);
+    if (w.waiting_on && w.waiting_since && Number.isFinite(Date.parse(w.waiting_since)) && t - Date.parse(w.waiting_since) >= WORK_WAIT_DAYS * DAY) {
+      b('work-waiting', 'agent', `Waiting on ${w.waiting_on} for ${Math.floor((t - Date.parse(w.waiting_since)) / DAY)} days`);
+    }
+    if (w.untouched) b('work-untouched', 'agent', `Untouched for ${WORK_UNTOUCHED_DAYS} days or more`);
+    if (['today', 'upcoming', 'waiting'].includes(w.placement) && !(w.steps > 0)) b('work-no-next-step', 'agent', 'No next step');
+  }
+  return out;
+}
+
+/** The lines the sweep appends now: one `blocker` per blocker per day, and for an agent blocker one `wake`. A target the PM
+ * is blocking (an open proposal older than a day) starts no run, so its other blockers wake nothing; the pm-open blocker is
+ * written once a day, which is what raises its Needs you row again. */
+function sweepLines(facts, state, { now, stalledDays } = {}) {
+  const t = now == null ? facts.now : now;
+  const day = facts.day || localDay(t);
+  const blockers = detect(facts, state, { now: t, stalledDays });
+  const pmBlocked = new Set(blockers.filter((b) => b.owner === 'pm').map((b) => targetKey(b.target)));
+  const lines = [];
+  for (const b of blockers) {
+    if (state.blockerDays.has(`${b.key}|${day}`)) continue;
+    lines.push({ ev: 'blocker', key: b.key, day, target: b.target, board: b.board, code: b.code, owner: b.owner, text: b.text });
+    if (b.owner === 'agent' && !pmBlocked.has(targetKey(b.target))) {
+      const key = `stuck:${b.key}:${day}`;
+      if (!state.wakeKeys.has(key)) lines.push({ ev: 'wake', key, target: b.target, board: b.board, reason: 'stuck', blocker: b.code });
+    }
+  }
+  return { blockers, lines };
+}
+
+// ── the wakes ────────────────────────────────────────────────────────────────────────────────────────
+/** `created`: placements lines { ev: 'created', initiative, at }. `moved`: boards ledger lines { kind: 'move', id, to, at, board }.
+ * Only events after the ledger's epoch wake a run: the first scan of a ledger marks what already happened as history. */
+function wakesFromLedgers({ created = [], moved = [] } = {}, state, { ws, epoch, boardOf = () => null } = {}) {
+  const lines = [];
+  const after = (at) => Number.isFinite(Date.parse(at)) && Number.isFinite(Date.parse(epoch)) && Date.parse(at) >= Date.parse(epoch);
+  for (const c of created) {
+    if (!c || c.ev !== 'created' || typeof c.initiative !== 'string' || !ID_RE.test(c.initiative) || !after(c.at)) continue;
+    const key = `created:${ws}:${c.initiative}`;
+    if (state.wakeKeys.has(key)) continue;
+    lines.push({ ev: 'wake', key, target: { kind: 'initiative', ws, id: c.initiative }, board: boardOf(c.initiative), reason: 'created' });
+  }
+  for (const m of moved) {
+    if (!m || m.kind !== 'move' || typeof m.id !== 'string' || !ID_RE.test(m.id) || !after(m.at)) continue;
+    const key = `moved:${ws}:${m.id}:${m.at}`;
+    if (state.wakeKeys.has(key)) continue;
+    lines.push({ ev: 'wake', key, target: { kind: 'initiative', ws, id: m.id }, board: m.board || boardOf(m.id), reason: 'moved' });
+  }
+  return lines;
+}
+/** A proposal the PM sent back with a note wakes a run for its target (once per proposal). */
+function answeredWakes(state, { boardOf = () => null } = {}) {
+  const lines = [];
+  for (const p of state.proposals.values()) {
+    if (p.state !== 'returned') continue;
+    const key = `answered:${p.id}`;
+    if (state.wakeKeys.has(key)) continue;
+    lines.push({ ev: 'wake', key, target: p.target, board: p.target.kind === 'work' ? 'work' : boardOf(p.target.id), reason: 'answered' });
+  }
+  return lines;
+}
+
+/** The run that was alive for an agent session token (its session id part), or null. */
+function runOfSession(state, token) {
+  if (typeof token !== 'string') return null;
+  return state.bySession.get(token.replace(/\.[0-9a-f]{8}$/, '')) || null;
+}
+
+module.exports = {
+  LEDGER, KINDS, WHATS, NEEDS_SOURCE, MODES, DEFAULT_MODE, WAKES, EVENTS, BUDGET, DAY, PM_WAIT_MS, SWEEP_EVERY_MS, DEFAULT_STALLED_DAYS, ID_RE, WS_RE, PROPOSAL_RE, RUN_RE,
+  stateDirOf, ledgerFile, append, readLines, newId, checkTarget, checkProposal, fold, modeOf, isPaused, openProposals, runsOnDay, admit, plan,
+  detect, sweepLines, wakesFromLedgers, answeredWakes, runOfSession, localDay, targetKey, wsIdOf,
+};

package/workspace/lib/extension-cli.js

@@ -0,0 +1,39 @@
+'use strict';
+/* extension-cli.js — `pmos extension`: where the Chrome extension for Google Meet is, and how to load it (initiative c3-meet-extension).
+ *
+ *   pmos extension    print the absolute path of workspace/extension and the steps to load it in Chrome
+ *
+ * The extension is a folder of plain files that ships in the workspace package. Chrome loads it unpacked, so nothing is installed or written here.
+ * It reads nothing and starts nothing; it does not need a running server. */
+const fs = require('fs');
+const path = require('path');
+
+const COMMANDS = { extension: [] };
+const FOLDER = path.resolve(__dirname, '..', 'extension');
+const USAGE = ['usage: pmos extension — the Chrome extension that shows the meeting companion over a Google Meet call'];
+
+/** The lines `pmos extension` prints for a folder. Pure. */
+function lines(folder, exists = true) {
+  const out = [];
+  if (!exists) { out.push(`✗ the extension folder is not here: ${folder}`, '  Reinstall the workspace with `pmos upgrade`.'); return out; }
+  out.push('PMOS for Google Meet (Chrome)', '', `  folder  ${folder}`, '',
+    'Load it in three steps:',
+    '  1. In Chrome, open chrome://extensions',
+    '  2. Turn on Developer mode (top right)',
+    '  3. Press Load unpacked, then pick the folder above',
+    '',
+    'PMOS is looked for at http://localhost:7433. If pmos printed another port, open the extension\'s Options and set that address.',
+    'Then open a Google Meet call: the panel shows at the bottom right.');
+  return out;
+}
+
+function run(argv, { say = console.log } = {}) {
+  const rest = (argv || []).slice(1);
+  if (rest.includes('--help') || rest.includes('-h') || rest[0] === 'help') { for (const l of USAGE) say(l); return 0; }
+  if (rest.length) { say(`✗ pmos extension takes no arguments (got "${rest[0]}")`); for (const l of USAGE) say(l); return 2; }
+  const exists = fs.existsSync(path.join(FOLDER, 'manifest.json'));
+  for (const l of lines(FOLDER, exists)) say(l);
+  return exists ? 0 : 1;
+}
+
+module.exports = { run, lines, COMMANDS, USAGE, FOLDER };