create-pmos 0.38.8 → 0.40.0

package/workspace/lib/proactive.js

@@ -0,0 +1,208 @@
+'use strict';
+/* proactive.js — the proactive engine's pure core (initiative `proactive-engine`, slice D1).
+ *
+ * The workspace used to wait to be asked. This module notices what needs the PM, from facts the repositories already
+ * hold, ranks it, and validates the feedback the PM gives about it. It is pure: no I/O, no clock, no model, no network.
+ * The server gathers the facts (ledgers and git) and persists the records; this decides.
+ *
+ *   detect(ctx)              the candidates that are true NOW — a condition that has ended is simply not returned
+ *   rank(cands)              the fixed, stated order
+ *   newSignals(...)          which candidates have not been appended to signals.jsonl inside the dedupe window
+ *   dismissedIds(...)        which candidates the PM dismissed within the last seven days
+ *   validateFeedback(body)   the four verdicts, the implicit events, an optional one-line note
+ *   normalizeSettings(raw)   off, per-trigger off, quiet hours, the stall threshold, pause learning
+ *   inQuietHours(now, quiet) whether automatic scans are held
+ *
+ * A candidate is never a status. Nothing here changes an initiative, a lifecycle line or an acceptance.
+ */
+const crypto = require('crypto');
+
+const TRIGGERS = ['needs', 'returned', 'review', 'schedule', 'stalled'];
+const VERDICTS = ['useful', 'not-useful', 'wrong-priority', 'missed'];
+const EVENTS = ['opened', 'acted', 'dismissed', 'ignored'];
+const DAY = 86400000;
+const DEDUPE_MS = DAY;
+const DISMISS_MS = 7 * DAY;
+
+// The fixed ranking, stated to the PM: what blocks on them first, then an unreviewed session, then a failed schedule,
+// then a stalled initiative. Within a kind, older first (age in days, capped at 30).
+const BASE = { needs: 100, returned: 100, review: 80, schedule: 60, stalled: 40 };
+const OWNER = { needs: 'pm', returned: 'pm', review: 'pm', schedule: 'pm', stalled: 'agent' };
+
+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 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);
+const days = (ms) => Math.floor(ms / DAY);
+
+function cand(kind, key, p) {
+  return { id: idOf(key), key, kind, owner: OWNER[kind], initiative_id: p.initiative_id || null, ws: p.ws || null, repo: p.repo || null,
+    title: clip(p.title, 120), why: clip(p.why, 200), evidence: clip(p.evidence, 240), confidence: p.confidence, since: p.since == null ? null : p.since,
+    open: p.open || null };
+}
+
+/**
+ * @param {{now:number, settings:object, repos:Array, nextStepRuns:Array}} ctx
+ *   repos[]: {name, ws, error?, initiatives:[{id,title,active,lastRun,hasRuns}], needs:[{initiative_id,question,run_id}],
+ *            returned:[{initiative_id,note,at}], schedules:[{id,name,lastStatus,lastRun}]}
+ *   nextStepRuns[]: {session_id, initiative_id, ws, key, ended, reviewed, at}
+ * @returns {{candidates:Array, unreadable:Array<{repo:string,error:string}>}}
+ */
+function detect(ctx) {
+  const now = ctx.now; const st = ctx.settings || DEFAULTS; const on = (t) => st.triggers ? st.triggers[t] !== false : true;
+  const out = []; const unreadable = [];
+  for (const r of ctx.repos || []) {
+    if (r.error) { unreadable.push({ repo: r.name, error: clip(r.error, 200) }); continue; }
+    const byId = new Map((r.initiatives || []).map((i) => [i.id, i]));
+    if (on('needs')) {
+      for (const n of r.needs || []) {
+        const ini = byId.get(n.initiative_id);
+        out.push(cand('needs', `needs:${r.ws}:${n.run_id || n.initiative_id + ':' + clip(n.question, 60)}`, {
+          initiative_id: n.initiative_id, ws: r.ws, repo: r.name, title: ini ? ini.title || ini.id : (n.initiative_id || 'an open item'),
+          why: 'An open item is waiting on you.', evidence: n.question, confidence: 0.95, since: null,
+          open: n.initiative_id ? { type: 'initiative', initiative_id: n.initiative_id, ws: r.ws } : null }));
+      }
+    }
+    if (on('returned')) {
+      for (const x of r.returned || []) {
+        const ini = byId.get(x.initiative_id);
+        if (ini && !ini.active) continue;
+        out.push(cand('returned', `returned:${r.ws}:${x.initiative_id}:${x.at || ''}`, {
+          initiative_id: x.initiative_id, ws: r.ws, repo: r.name, title: ini ? ini.title || ini.id : x.initiative_id,
+          why: 'You returned this at the Acceptance Gate and it has not been accepted since.', evidence: x.note || 'returned', confidence: 0.95, since: x.at ? Date.parse(x.at) || null : null,
+          open: { type: 'initiative', initiative_id: x.initiative_id, ws: r.ws } }));
+      }
+    }
+    if (on('schedule')) {
+      for (const s of r.schedules || []) {
+        if (s.lastStatus !== 'fail') continue;
+        out.push(cand('schedule', `schedule:${s.id}:${s.lastRun || ''}`, {
+          ws: r.ws, repo: r.name, title: s.name || s.id, why: 'A scheduled task failed on its last run.',
+          evidence: `${s.name || s.id} — last run ${s.lastRun ? new Date(s.lastRun).toISOString().slice(0, 16).replace('T', ' ') : 'unknown'} reported fail`,
+          confidence: 0.9, since: s.lastRun ? Date.parse(s.lastRun) || null : null, open: { type: 'schedule', id: s.id, ws: r.ws } }));
+      }
+    }
+    if (on('stalled')) {
+      const limit = (st.stalledDays || DEFAULTS.stalledDays) * DAY;
+      for (const i of r.initiatives || []) {
+        if (!i.active || !i.hasRuns || i.lastRun == null) continue;
+        const idle = now - i.lastRun;
+        if (idle < limit) continue;
+        const d = days(idle);
+        out.push(cand('stalled', `stalled:${r.ws}:${i.id}`, {
+          initiative_id: i.id, ws: r.ws, repo: r.name, title: i.title || i.id,
+          why: `In progress, with no agent run for ${d} days.`, evidence: `last run ${new Date(i.lastRun).toISOString().slice(0, 10)}; the threshold is ${st.stalledDays || DEFAULTS.stalledDays} days`,
+          confidence: Math.min(0.85, +(0.5 + 0.05 * (d - (st.stalledDays || DEFAULTS.stalledDays))).toFixed(2)), since: i.lastRun,
+          open: { type: 'initiative', initiative_id: i.id, ws: r.ws } }));
+      }
+    }
+  }
+  if (on('review')) {
+    for (const x of ctx.nextStepRuns || []) {
+      if (!x.ended || x.reviewed) continue;
+      out.push(cand('review', `review:${x.session_id}`, {
+        initiative_id: x.initiative_id, ws: x.ws, repo: null, title: `${x.key || 'a step'} · ${x.initiative_id}`,
+        why: 'A session started from a next step has ended and has no verdict from you.', evidence: `session ${x.session_id}`, confidence: 0.9, since: x.at ? Date.parse(x.at) || null : null,
+        open: { type: 'review', initiative_id: x.initiative_id, ws: x.ws, session_id: x.session_id } }));
+    }
+  }
+  return { candidates: out, unreadable };
+}
+
+function rank(cands, now) {
+  const score = (c) => BASE[c.kind] + (c.since != null && now != null ? Math.min(30, Math.max(0, days(now - c.since))) : 0);
+  return cands.map((c) => ({ ...c, rank: score(c) })).sort((a, b) => b.rank - a.rank || (a.id < b.id ? -1 : 1))
+    .map((c, i) => ({ ...c, n: i + 1 }));
+}
+
+/** Candidates whose key was not already appended within the dedupe window. `recent` = signals.jsonl rows `{key, at}`. */
+function newSignals(cands, recent, now) {
+  const seen = new Set();
+  for (const r of recent || []) { const t = Date.parse(r && r.at); if (r && r.key && Number.isFinite(t) && now - t < DEDUPE_MS) seen.add(r.key); }
+  return cands.filter((c) => !seen.has(c.key));
+}
+
+/** The ids the PM dismissed inside the dismissal window. `feedback` = proactive-feedback.jsonl rows. */
+function dismissedIds(feedback, now) {
+  const out = new Set();
+  for (const f of feedback || []) {
+    if (!f || f.event !== 'dismissed' || !f.candidate_id) continue;
+    const t = Date.parse(f.at);
+    if (Number.isFinite(t) && now - t < DISMISS_MS) out.add(f.candidate_id);
+  }
+  return out;
+}
+
+const ID_RE = /^[0-9a-f]{12}$/;
+/** @returns {{ok:true, record:object}|{ok:false, error:string}} — a verdict, or an implicit event, never both. */
+function validateFeedback(body) {
+  const b = body && typeof body === 'object' ? body : {};
+  const note = clip(b.note, 300);
+  const hasVerdict = b.verdict !== undefined && b.verdict !== null && b.verdict !== '';
+  const hasEvent = b.event !== undefined && b.event !== null && b.event !== '';
+  if (hasVerdict === hasEvent) return { ok: false, error: `give a verdict (${VERDICTS.join(', ')}) or an event (${EVENTS.join(', ')}), not both and not neither` };
+  if (hasVerdict) {
+    if (!VERDICTS.includes(b.verdict)) return { ok: false, error: `verdict must be one of ${VERDICTS.join(', ')}` };
+    if (b.verdict === 'missed') {
+      if (!note) return { ok: false, error: 'say what was missed: a "missed" verdict needs a note' };
+      if (b.candidate_id !== undefined && b.candidate_id !== null && b.candidate_id !== '' && !ID_RE.test(String(b.candidate_id))) return { ok: false, error: 'candidate_id is not a candidate id' };
+      return { ok: true, record: { kind: 'verdict', candidate_id: b.candidate_id || null, verdict: 'missed', note } };
+    }
+  } else if (!EVENTS.includes(b.event)) return { ok: false, error: `event must be one of ${EVENTS.join(', ')}` };
+  if (!ID_RE.test(String(b.candidate_id || ''))) return { ok: false, error: 'candidate_id is required and must be a candidate id' };
+  return hasVerdict ? { ok: true, record: { kind: 'verdict', candidate_id: b.candidate_id, verdict: b.verdict, note } }
+    : { ok: true, record: { kind: 'event', candidate_id: b.candidate_id, event: b.event, note } };
+}
+
+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 };
+  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.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)) {
+      if (!BRIEF_SOURCES.includes(k)) return { ok: false, error: `unknown brief source "${k}" — one of ${BRIEF_SOURCES.join(', ')}` };
+      if (typeof v !== 'boolean') return { ok: false, error: `brief source "${k}" must be true or false` };
+      s.briefSources[k] = v;
+    }
+  }
+  if (r.pauseLearning !== undefined) { if (typeof r.pauseLearning !== 'boolean') return { ok: false, error: 'pauseLearning must be true or false' }; s.pauseLearning = r.pauseLearning; }
+  if (r.triggers !== undefined) {
+    if (!r.triggers || typeof r.triggers !== 'object' || Array.isArray(r.triggers)) return { ok: false, error: `triggers must be an object of ${TRIGGERS.join(', ')} → true or false` };
+    for (const [k, v] of Object.entries(r.triggers)) {
+      if (!TRIGGERS.includes(k)) return { ok: false, error: `unknown trigger "${k}" — one of ${TRIGGERS.join(', ')}` };
+      if (typeof v !== 'boolean') return { ok: false, error: `trigger "${k}" must be true or false` };
+      s.triggers[k] = v;
+    }
+  }
+  if (r.stalledDays !== undefined) {
+    const n = Number(r.stalledDays);
+    if (!Number.isInteger(n) || n < 1 || n > 90) return { ok: false, error: 'stalledDays must be a whole number from 1 to 90' };
+    s.stalledDays = n;
+  }
+  if (r.quiet !== undefined) {
+    if (r.quiet === null) s.quiet = null;
+    else if (!r.quiet || typeof r.quiet !== 'object' || !HHMM.test(String(r.quiet.start)) || !HHMM.test(String(r.quiet.end)) || r.quiet.start === r.quiet.end) {
+      return { ok: false, error: 'quiet must be null, or {start, end} as HH:MM (24-hour, local), different from each other' };
+    } else s.quiet = { start: r.quiet.start, end: r.quiet.end };
+  }
+  return { ok: true, settings: s };
+}
+
+/** Local time of day against a quiet window; a window that wraps midnight (22:00–07:00) is handled. */
+function inQuietHours(nowMs, quiet) {
+  if (!quiet) return false;
+  const d = new Date(nowMs); const m = d.getHours() * 60 + d.getMinutes();
+  const p = (s) => { const [h, mm] = s.split(':').map(Number); return h * 60 + mm; };
+  const a = p(quiet.start); const b = p(quiet.end);
+  return a < b ? m >= a && m < b : m >= a || m < b;
+}
+
+module.exports = { BRIEF_SOURCES, TRIGGERS, VERDICTS, EVENTS, DEFAULTS, DEDUPE_MS, DISMISS_MS, BASE, detect, rank, newSignals, dismissedIds, validateFeedback, normalizeSettings, inQuietHours };

package/workspace/lib/repo-watch.js

@@ -0,0 +1,120 @@
+'use strict';
+/* repo-watch.js — notice that files in a repository changed, and ask for one check (claims-ledger C8).
+ *
+ * WHY A POLL AND NOT fs.watch. A recursive watch needs Node 20 on Linux and can hit the inotify limit on a big tree,
+ * and it still would not see a `git checkout` or a `git pull`. The signature below changes for all of them: an edit in
+ * the editor, a write by an agent in a terminal, a checkout, a pull.
+ *
+ * THE SIGNATURE. `git rev-parse HEAD`, plus the porcelain status, plus the mtime and size of each dirty file — a file
+ * edited twice shows the same status line twice, so the status alone would miss the second edit. A folder that is not
+ * a git checkout uses the mtime and size of its in-scope files.
+ *
+ * DEBOUNCE. An agent writes many files in a burst. A change starts the clock; the check runs once the signature has
+ * stayed the same for `stableMs`. A burst that keeps changing keeps postponing, and ends as ONE run.
+ *
+ * WHAT IT NEVER DOES. It runs async git only, with read-only verbs. It opens no network connection and calls no git
+ * network verb. It never runs a second check for a repository while one is in flight. It checks only repositories
+ * `enabled(root)` says to, and the PM can switch that off per repository.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFile } = require('child_process');
+
+const sha = (s) => crypto.createHash('sha1').update(s).digest('hex');
+const DIRTY_STAT_CAP = 500;
+
+function git(root, args) {
+  return new Promise((resolve) => {
+    execFile('git', args, { cwd: root, maxBuffer: 32 << 20, timeout: 15000, encoding: 'utf8' }, (err, out) => resolve(err ? null : out));
+  });
+}
+
+/** One string that changes whenever the repository's files change. `null` when the folder cannot be read at all. */
+async function signature(root, listFiles) {
+  const head = await git(root, ['rev-parse', 'HEAD']);
+  const status = head == null ? null : await git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']);
+  const parts = [];
+  if (head != null && status != null) {
+    parts.push(head.trim(), sha(status));
+    const dirty = status.split('\0').filter((e) => e.length > 3).map((e) => e.slice(3)).slice(0, DIRTY_STAT_CAP);
+    for (const rel of dirty) {
+      try { const st = fs.statSync(path.join(root, rel)); parts.push(rel + ':' + st.mtimeMs + ':' + st.size); } catch { parts.push(rel + ':gone'); }
+    }
+    return sha(parts.join('\n'));
+  }
+  // not a git checkout: the mtime and size of every in-scope file
+  let files = [];
+  try { files = (await listFiles(root)).files; } catch { return null; }
+  for (const rel of files) {
+    try { const st = fs.statSync(path.join(root, rel)); parts.push(rel + ':' + st.mtimeMs + ':' + st.size); } catch { parts.push(rel + ':gone'); }
+  }
+  return sha(parts.join('\n'));
+}
+
+/**
+ * @param {object} o
+ * @param {function} o.repos            () => [{ id, root }]  the repositories that exist
+ * @param {function} o.enabled          (root) => boolean     whether to watch this one
+ * @param {function} o.check            async ({ root, sweep }) => result   one check
+ * @param {function} [o.signature]      async (root) => string|null
+ * @param {function} [o.onResult]       ({ id, root, ok, result|error, sweep })
+ * @param {function} [o.now]            () => ms
+ * @param {number}   [o.pollMs]         how often the timer ticks
+ * @param {number}   [o.stableMs]       how long the signature must hold still before a check
+ * @param {number}   [o.sweepEveryMs]   how often the periodic time-rule pass runs
+ */
+function createWatcher(o) {
+  const now = o.now || Date.now;
+  const pollMs = o.pollMs || 10000;
+  const stableMs = o.stableMs == null ? 8000 : o.stableMs;
+  const sweepEveryMs = o.sweepEveryMs || 6 * 3600 * 1000;
+  const sigOf = o.signature || ((root) => signature(root, o.listFiles || (async () => ({ files: [] }))));
+  const state = new Map();                       // root → { sig, changedAt, pending, running, lastSweep, checked }
+  let timer = null;
+  let ticking = false;
+
+  async function run(id, root, st, sweep) {
+    st.running = true;
+    try {
+      const result = await o.check({ root, sweep });
+      if (o.onResult) o.onResult({ id, root, ok: !!(result && result.ok !== false), result, sweep });
+    } catch (e) {
+      if (o.onResult) o.onResult({ id, root, ok: false, error: String((e && e.message) || e).slice(0, 200), sweep });
+    } finally { st.running = false; st.checked = true; if (sweep) st.lastSweep = now(); }
+  }
+
+  /** One pass over every repository. Exposed so a test can drive it with a fake clock. */
+  async function tick() {
+    if (ticking) return;
+    ticking = true;
+    try {
+      const live = new Set();
+      for (const r of o.repos()) {
+        if (!o.enabled(r.root)) { state.delete(r.root); continue; }
+        live.add(r.root);
+        let st = state.get(r.root);
+        if (!st) { st = { sig: null, changedAt: null, pending: false, running: false, lastSweep: now(), checked: false }; state.set(r.root, st); }
+        if (st.running) continue;                                    // never two checks at once for one repository
+        const sig = await sigOf(r.root);
+        if (sig == null) continue;
+        if (!st.checked && !st.pending && st.sig == null) { st.sig = sig; await run(r.id, r.root, st, false); continue; }   // first look: one check
+        if (sig !== st.sig) { st.sig = sig; st.changedAt = now(); st.pending = true; continue; }
+        if (st.pending && now() - st.changedAt >= stableMs) { st.pending = false; await run(r.id, r.root, st, false); continue; }
+        if (!st.pending && now() - st.lastSweep >= sweepEveryMs) await run(r.id, r.root, st, true);
+      }
+      for (const root of Array.from(state.keys())) if (!live.has(root)) state.delete(root);
+    } finally { ticking = false; }
+  }
+
+  function start() {
+    if (timer) return stop;
+    timer = setInterval(() => { tick().catch(() => { /* a failed tick is retried on the next one */ }); }, pollMs);
+    if (timer.unref) timer.unref();
+    return stop;
+  }
+  function stop() { if (timer) { clearInterval(timer); timer = null; } }
+  return { tick, start, stop, _state: state };
+}
+
+module.exports = { createWatcher, signature };

package/workspace/lib/schedule-cli.js

@@ -245,7 +245,7 @@ async function run(argv, { call, say, cwd = process.cwd() }) {
 }
 
 function usage(say) {
-  say('usage: pmos schedule <list|show|add|edit|run|enable|disable|rm> …   |   pmos skill <list|show|new|edit|copy> …');
+  say(`usage: pmos schedule <${COMMANDS.schedule.join('|')}> …   |   pmos skill <${COMMANDS.skill.join('|')}> …`);
   say('  pmos schedule add --skill gather-requirements --cadence daily --time 07:30 [--until 2026-12-31] [--max-runs 20]');
   say('  pmos schedule add --from-session <id> --skill-name my-check --cadence weekly --day Fri --time 16:00');
   say('  pmos schedule edit <id|name> --time 08:00 --args "focus on the billing initiative" --tier deep --until none');
@@ -253,4 +253,7 @@ function usage(say) {
   say('  schedules fire only while the workspace server is running.');
 }
 
-module.exports = { run, parseArgs, fieldsFrom };
+// The commands this module answers, in one place: the usage line below and the user guide's drift test both read it.
+const COMMANDS = { schedule: ['list', 'show', 'add', 'edit', 'run', 'enable', 'disable', 'rm'], skill: ['list', 'show', 'new', 'edit', 'copy'] };
+
+module.exports = { run, parseArgs, fieldsFrom, COMMANDS };

package/workspace/lib/secret-scan.js

@@ -0,0 +1,28 @@
+'use strict';
+/* secret-scan.js — a local check that runs BEFORE any repository text is sent anywhere (D79, V7).
+ *
+ * It returns the NAMES of the rules that matched and never the matched text, so a finding or a log
+ * line built from the result cannot carry the secret. A green scan is not proof that a text is
+ * clean: the per-repository consent switch is the real control, and this is the second line.
+ */
+const RULES = [
+  ['private-key-block', /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ['aws-access-key', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/],
+  ['github-token', /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{40,})\b/],
+  ['slack-token', /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/],
+  ['api-key-sk', /\bsk[-_](?:live|test|ant|proj)?[-_]?[A-Za-z0-9_-]{20,}\b/],
+  ['google-api-key', /\bAIza[0-9A-Za-z_-]{35}\b/],
+  ['jwt', /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/],
+  ['url-with-password', /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]{3,}@[^\s/]+/i],
+  ['assigned-secret', /\b(?:api[_-]?key|secret|token|passwd|password)\b["']?\s*[:=]\s*["']?[A-Za-z0-9/+_.\-]{16,}/i],
+];
+
+/** @returns {string[]} names of the rules that matched; empty when none did. */
+function scan(text) {
+  const t = String(text == null ? '' : text);
+  const hits = [];
+  for (const [name, re] of RULES) if (re.test(t)) hits.push(name);
+  return hits;
+}
+
+module.exports = { scan, RULES: RULES.map(([n]) => n) };

package/workspace/lib/session-budget.js

@@ -0,0 +1,35 @@
+'use strict';
+/* session-budget.js — how many sessions the workspace may start on the PM's behalf.
+ *
+ * Only sessions started from a next step (origin `next-step`) are counted and limited. A session the PM starts by hand
+ * is never counted and never blocked: the budget protects against the workspace spending, not against the PM working.
+ * Pure: the caller passes what is running and what started today.
+ */
+const DEFAULTS = Object.freeze({ concurrent: 3, perDay: 8 });
+const RANGE = { concurrent: [1, 20], perDay: [1, 100] };
+
+/** @returns {{ok:true,limits}|{ok:false,error}} */
+function normalizeLimits(v) {
+  const raw = v && typeof v === 'object' ? v : {};
+  const out = { ...DEFAULTS };
+  for (const k of ['concurrent', 'perDay']) {
+    if (raw[k] === undefined) continue;
+    const n = Number(raw[k]);
+    if (!Number.isInteger(n) || n < RANGE[k][0] || n > RANGE[k][1]) return { ok: false, error: `${k === 'perDay' ? 'per day' : k} must be a whole number from ${RANGE[k][0]} to ${RANGE[k][1]}` };
+    out[k] = n;
+  }
+  return { ok: true, limits: out };
+}
+
+/** @param {{running:number, startedToday:number, limits?:object}} s */
+function check(s) {
+  const n = normalizeLimits(s && s.limits);
+  const limits = n.ok ? n.limits : { ...DEFAULTS };
+  const running = Math.max(0, Number(s && s.running) || 0);
+  const startedToday = Math.max(0, Number(s && s.startedToday) || 0);
+  if (running >= limits.concurrent) return { allowed: false, reason: `${running} prepared sessions are already running (limit ${limits.concurrent}). End one or raise the limit.`, running, startedToday, limits };
+  if (startedToday >= limits.perDay) return { allowed: false, reason: `${startedToday} sessions were started today (limit ${limits.perDay}). Raise the limit to start more.`, running, startedToday, limits };
+  return { allowed: true, reason: null, running, startedToday, limits };
+}
+
+module.exports = { DEFAULTS, normalizeLimits, check };

package/workspace/lib/status-groups.js

@@ -18,17 +18,60 @@
 
   // In the order the PM reads them: what needs them, what is moving, what has not started, what waits on
   // their acceptance, what is done, then what is parked. `active` marks the four that are live work.
+  // Every group states five things, so the legend on the screen and the grouping cannot disagree:
+  //   meaning   what the PM is being told
+  //   source    the fact it is read from (a ledger line or git), never a typed field
+  //   owner     who has to act: pm | agent | system
+  //   moves     what takes an initiative out of this group, and where it goes
+  //   pmCan     what the PM can do by hand here (only hold, close, cancel and reopen are written; the rest is derived)
   const GROUPS = [
-    { key: 'needs-you', label: 'Needs you', active: true, hint: 'returned at acceptance, or has open items in the needs queue' },
-    { key: 'in-progress', label: 'In progress', active: true, hint: 'runs logged, nothing merged yet' },
-    { key: 'planning', label: 'Planning', active: true, hint: 'recorded, no run logged yet' },
-    { key: 'awaiting-acceptance', label: 'Awaiting acceptance', active: true, hint: 'delivered; the PM has not accepted it' },
-    { key: 'accepted', label: 'Accepted', active: false, hint: 'accepted by the PM' },
-    { key: 'on-hold', label: 'On hold', active: false, hint: 'paused by the PM; off the board, not gating' },
-    { key: 'closed', label: 'Closed', active: false, hint: 'closed by the PM; off the board, not gating' },
-    { key: 'cancelled', label: 'Cancelled', active: false, hint: 'cancelled by the PM; off the board, not gating' },
-    { key: 'unknown', label: 'Unknown', active: false, hint: 'the history could not be read, so the status cannot be derived' },
+    { key: 'needs-you', label: 'Needs you', active: true, hint: 'returned at acceptance, or has open items in the needs queue',
+      meaning: 'Work is stopped on a decision or an answer only you can give.',
+      source: 'acceptances.jsonl (your latest acceptance row is a return) or the needs queue (an open item names this initiative)',
+      owner: 'pm', moves: 'When the open items are cleared, or you accept after the agent addresses the return, it moves to In progress or Awaiting acceptance.',
+      pmCan: 'Answer the items listed in the detail. You can also hold, close or cancel it.' },
+    { key: 'in-progress', label: 'In progress', active: true, hint: 'runs logged, nothing merged yet',
+      meaning: 'An agent run is logged and nothing has been merged yet.',
+      source: 'agent-runs.jsonl has at least one run for it, and no initiative/<id> branch is merged',
+      owner: 'agent', moves: 'When its branch is merged it moves to Awaiting acceptance. An open needs item moves it to Needs you.',
+      pmCan: 'Read the next steps and the conversations. You can hold, close or cancel it.' },
+    { key: 'planning', label: 'Planning', active: true, hint: 'recorded, no run logged yet',
+      meaning: 'The initiative is recorded and no agent run has started.',
+      source: 'the initiative record exists; agent-runs.jsonl has no run for it',
+      owner: 'agent', moves: 'When the first run is logged it moves to In progress.',
+      pmCan: 'Review what the agent drafts. You can also hold, close or cancel it.' },
+    { key: 'awaiting-acceptance', label: 'Awaiting acceptance', active: true, hint: 'delivered; the PM has not accepted it',
+      meaning: 'The work is delivered and waits for your acceptance. Acceptance is yours alone (D12).',
+      source: 'git: an initiative/<id> branch was merged, or a trunk commit names the initiative and changes build files; no acceptance row yet',
+      owner: 'pm', moves: 'When you record an acceptance it moves to Accepted. If you return it, it moves to Needs you.',
+      pmCan: 'Open the Acceptance Gate and accept or return it. You can also hold, close or cancel it.' },
+    { key: 'accepted', label: 'Accepted', active: false, hint: 'accepted by the PM',
+      meaning: 'You accepted it. Nothing remains.',
+      source: 'acceptances.jsonl (your latest acceptance row accepts)',
+      owner: 'system', moves: 'It stays here.',
+      pmCan: 'Nothing to do. Close it only if you want it off the board.' },
+    { key: 'on-hold', label: 'On hold', active: false, hint: 'paused by the PM; off the board, not gating',
+      meaning: 'You paused it. It is off the board and does not block anything.',
+      source: 'lifecycle.jsonl (your latest line for it is on-hold)',
+      owner: 'pm', moves: 'It stays here until you reopen it. It then returns to the group its facts give.',
+      pmCan: 'Reopen it.' },
+    { key: 'closed', label: 'Closed', active: false, hint: 'closed by the PM; off the board, not gating',
+      meaning: 'You closed it. It is off the board and does not block anything.',
+      source: 'lifecycle.jsonl (your latest line for it is closed)',
+      owner: 'pm', moves: 'It stays here until you reopen it.',
+      pmCan: 'Reopen it.' },
+    { key: 'cancelled', label: 'Cancelled', active: false, hint: 'cancelled by the PM; off the board, not gating',
+      meaning: 'You cancelled it. It is off the board and does not block anything.',
+      source: 'lifecycle.jsonl (your latest line for it is cancelled)',
+      owner: 'pm', moves: 'It stays here until you reopen it.',
+      pmCan: 'Reopen it.' },
+    { key: 'unknown', label: 'Unknown', active: false, hint: 'the history could not be read, so the status cannot be derived',
+      meaning: 'The status could not be worked out, so none is shown.',
+      source: 'the trunk history or the ledgers could not be read',
+      owner: 'system', moves: 'When the history can be read again it moves to the group its facts give.',
+      pmCan: 'Check that the repository is readable, then reload.' },
   ];
+  const LEGEND_FIELDS = ['meaning', 'source', 'owner', 'moves', 'pmCan'];
   const BY_KEY = Object.fromEntries(GROUPS.map((g) => [g.key, g]));
 
   /** The group key for one derived status row `{status, lifecycle}`; `unknown` when the row is missing or unrecognised. */
@@ -62,5 +105,5 @@
       .map((g) => ({ ...g, slugs: buckets.get(g.key) }));
   }
 
-  return { GROUPS, BY_KEY, keyOf, group };
+  return { GROUPS, BY_KEY, LEGEND_FIELDS, keyOf, group };
 }));

package/workspace/lib/typesafe-settings.js

@@ -0,0 +1,122 @@
+'use strict';
+/* typesafe-settings.js — where the TypeSafe key and the per-repository consent live (D79).
+ *
+ * The file is `<runtime state>/typesafe.json`, in the per-user runtime directory that lib/state-root.js
+ * keeps OUTSIDE every repository, so no commit, sync or share can carry it. It is written with mode 0600
+ * through a temporary file and a rename, and a symlink at the target is refused.
+ *
+ * What leaves this module: `status()` says whether a key is present and where it came from. It never
+ * returns the key. `getKey()` is for the server's validation path only; no route returns its value.
+ * `TYPESAFE_API_KEY` in the environment is read as a fallback, ONCE, at server start (`adoptEnv`), which
+ * then deletes the variable from the process environment. Nothing the server spawns afterwards can see it.
+ */
+const fs = require('fs');
+const path = require('path');
+const { validKey } = require('./typesafe');
+
+const FILE = 'typesafe.json';
+const ENV_NAME = 'TYPESAFE_API_KEY';
+const MAX_EXCLUDES = 100;
+
+function file(stateDir) { return path.join(stateDir, FILE); }
+
+function read(stateDir) {
+  try {
+    const st = fs.lstatSync(file(stateDir));
+    if (!st.isFile()) return { key: null, repos: {} };
+    const o = JSON.parse(fs.readFileSync(file(stateDir), 'utf8'));
+    return {
+      key: typeof o.key === 'string' ? o.key : null,
+      repos: o && typeof o.repos === 'object' && o.repos && !Array.isArray(o.repos) ? o.repos : {},
+    };
+  } catch { return { key: null, repos: {} }; }
+}
+
+function write(stateDir, data) {
+  const target = file(stateDir);
+  try { if (fs.lstatSync(target).isSymbolicLink()) return { ok: false, error: 'the settings file is a symlink and was not written' }; }
+  catch { /* not there yet */ }
+  const tmp = target + '.' + process.pid + '.tmp';
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, target);
+    return { ok: true };
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch { /* nothing to clean */ }
+    return { ok: false, error: 'the settings could not be saved (' + String((e && e.code) || 'write failed') + ')' };
+  }
+}
+
+/* The environment key is TAKEN, not borrowed. `adoptEnv` moves it from the process environment into this
+ * module's memory and deletes the variable, so no child the server starts afterwards — a terminal, git, a
+ * schedule — inherits it. Called once at server start. */
+let adopted = null;
+function adoptEnv(env) {
+  if (env && validKey(env[ENV_NAME])) adopted = env[ENV_NAME];
+  if (env) delete env[ENV_NAME];
+}
+function envKey(env) { return adopted || (env && validKey(env[ENV_NAME]) ? env[ENV_NAME] : null); }
+
+/** The key for the server's own use, or null. File first, then the environment. */
+function getKey(stateDir, env = null) {
+  const f = read(stateDir).key;
+  if (validKey(f)) return f;
+  return envKey(env);
+}
+
+/** What the browser may know: present or not, and from where. Never the value, never its length. */
+function status(stateDir, env = null) {
+  if (validKey(read(stateDir).key)) return { present: true, source: 'settings' };
+  if (envKey(env)) return { present: true, source: 'environment' };
+  return { present: false, source: null };
+}
+
+function setKey(stateDir, key) {
+  const k = typeof key === 'string' ? key.trim() : '';
+  if (!validKey(k)) return { ok: false, error: 'that does not look like a key — it must be 8 to 512 characters with no spaces' };
+  const cur = read(stateDir);
+  return write(stateDir, { key: k, repos: cur.repos });
+}
+
+function clearKey(stateDir) {
+  const cur = read(stateDir);
+  return write(stateDir, { key: null, repos: cur.repos });
+}
+
+/** Consent and exclusions for one repository root. Consent defaults to off. */
+function getRepo(stateDir, root) {
+  const r = read(stateDir).repos[root];
+  return {
+    consent: !!(r && r.consent === true),
+    exclude: r && Array.isArray(r.exclude) ? r.exclude.filter((x) => typeof x === 'string') : [],
+    // claims-ledger: keep this repository checked as its files change. Default OFF — switching it on makes the
+    // workspace append to the repository's claims.jsonl, so it is the PM's press and never a surprise.
+    watch: !!(r && r.watch === true),
+  };
+}
+
+function setRepo(stateDir, root, { consent, exclude, watch }) {
+  const cur = read(stateDir);
+  const prev = getRepo(stateDir, root);
+  const ex = Array.isArray(exclude)
+    ? exclude.map((x) => String(x).trim().replace(/^\/+/, '')).filter((x) => x && !x.includes('..') && x.length <= 200).slice(0, MAX_EXCLUDES)
+    : prev.exclude;
+  const repos = { ...cur.repos, [root]: { consent: typeof consent === 'boolean' ? consent : prev.consent, exclude: ex, watch: typeof watch === 'boolean' ? watch : prev.watch } };
+  return write(stateDir, { key: cur.key, repos });
+}
+
+/** Does `rel` fall under an exclusion? An entry is a path prefix, or a `*` pattern matched on the path. */
+function isExcluded(exclude, rel) {
+  const p = String(rel).replace(/\\/g, '/');
+  return exclude.some((e) => {
+    if (e.includes('*')) {
+      const re = new RegExp('^' + e.split('*').map((s) => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$');
+      return re.test(p);
+    }
+    return p === e || p.startsWith(e.endsWith('/') ? e : e + '/');
+  });
+}
+
+module.exports = { adoptEnv, status, getKey, setKey, clearKey, getRepo, setRepo, isExcluded, ENV_NAME, FILE };