create-pmos 0.38.8 → 0.39.0

package/workspace/lib/next-step-actions.js

@@ -0,0 +1,139 @@
+'use strict';
+/* next-step-actions.js — what a next step can DO, whether it may be started yet, and the prompt a session would get.
+ *
+ * Pure: no I/O, no clock, no model. The server supplies facts (does a file exist, which sources a profile declares) and
+ * this module decides. Three questions, each answered in one place so no panel and no route re-decides them:
+ *
+ *   actFor(item)        what kind of act the step is: open · session · work · gate · lifecycle · none
+ *   refusal(item, ns)   why a `work` step may NOT be started yet, or null when it may
+ *   buildPrompt(...)    the exact first input a session would receive — what the PM is shown before pressing go
+ *
+ * THE BOUNDARY (D12 and the control/factory invariant). A session started from here PROPOSES: it commits to a local
+ * initiative branch or writes draft files. It never accepts, approves a contract, merges, pushes, sends or posts. Acceptance
+ * and the contract approval are `gate` acts and are never turned into `work`.
+ */
+const crypto = require('crypto');
+
+// Ladder steps an agent session can do. `contract`, `accept`, `approved`, `outcome` and `handoff` are the PM's own act.
+const WORK_KEYS = new Set(['route', 'anchor', 'prototype', 'understand', 'spec', 'priors', 'build', 'quality', 'review', 'explain', 'brief', 'draft']);
+const GATE_KEYS = new Set(['contract', 'accept', 'approved', 'outcome', 'handoff']);
+const KNOWN_KEYS = [...WORK_KEYS, ...GATE_KEYS];
+// The act types a step can have (`none` means no action is defined, and is not offered). The user guide names each one.
+const ACT_TYPES = ['open', 'session', 'work', 'gate', 'lifecycle'];
+
+const GATE_WHY = {
+  contract: 'The contract is yours to approve. An agent may draft it; the approval is recorded by you, never by a session.',
+  accept: 'Acceptance is yours and cannot be delegated (D12).',
+  approved: 'Approval is yours.',
+  outcome: 'The outcome check is yours to record.',
+  handoff: 'Handing work to another system is outward-facing, so it is yours to press.',
+};
+
+/** @returns {{type:'open'|'session'|'work'|'gate'|'lifecycle'|'none', why:string, path?:string, sessionId?:string}} */
+function actFor(item) {
+  if (!item || typeof item !== 'object') return { type: 'none', why: 'no step' };
+  const path = typeof item.path === 'string' && item.path ? item.path : null;
+  const withPath = (a) => (path ? { ...a, path } : a);
+  switch (item.kind) {
+    case 'reopen': return { type: 'lifecycle', why: 'Reopen it to put it back on the board.' };
+    case 'session': return item.sid ? { type: 'session', why: 'Switch to the running session.', sessionId: item.sid } : { type: 'none', why: 'the session is not identified' };
+    case 'accept': return withPath({ type: path ? 'open' : 'gate', why: GATE_WHY.accept });
+    case 'needs': return withPath({ type: 'gate', why: 'An open item only you can answer.' });
+    case 'returned': return { type: 'work', why: 'Address the return, then ask for acceptance again.' };
+    case 'step': {
+      if (WORK_KEYS.has(item.key)) return withPath({ type: 'work', why: 'An agent session can do this step.' });
+      if (GATE_KEYS.has(item.key)) return withPath({ type: path ? 'open' : 'gate', why: GATE_WHY[item.key] });
+      return { type: 'none', why: `no action is defined for the step "${item.key}"` };
+    }
+    default: return { type: 'none', why: 'no action is defined for this item' };
+  }
+}
+
+/** Set `act` on every item of a derived next-steps result. Mutates and returns it. */
+function annotate(ns, pathOf) {
+  if (!ns || !Array.isArray(ns.items)) return ns;
+  for (const it of ns.items) {
+    if (typeof pathOf === 'function') { const p = pathOf(it); if (p) it.path = p; }
+    it.act = actFor(it);
+  }
+  return ns;
+}
+
+/** Why this item may not be started as work yet; null when it may. `ns` is the whole derived result. */
+function refusal(item, ns) {
+  if (!item) return { code: 'no-step', why: 'no such step' };
+  const act = item.act || actFor(item);
+  if (ns && ns.state === 'stopped' && item.kind !== 'reopen') {
+    return { code: 'stopped', why: 'This initiative is stopped (held, closed or cancelled). Reopen it first.', first: 'reopen' };
+  }
+  if (ns && ns.state === 'accepted') return { code: 'accepted', why: 'This initiative is accepted. Nothing remains.' };
+  if (act.type !== 'work') return { code: 'not-work', why: act.type === 'gate' ? act.why : `This is not work an agent session can start (${act.type}).` };
+  const items = (ns && ns.items) || [];
+  if (item.kind === 'returned') return null;                      // addressing a return is always the next thing
+  if (item.status === 'blocked') return { code: 'blocked', why: `This step is blocked${item.why ? ' — ' + item.why : ''}.`, first: item.key };
+  if (item.key === 'build') {
+    const contract = items.find((x) => x.kind === 'step' && x.key === 'contract');
+    if (contract) return { code: 'no-contract', why: 'The build cannot start before you approve the pre-run contract. An agent may draft it; you approve it.', first: 'contract' };
+  }
+  if (item.first || item.status === 'current') return null;
+  const first = items.find((x) => x.first) || items[0];
+  return { code: 'not-reached', why: `Not reached yet: step ${first ? first.n : 1} (${first ? first.key : 'the first step'}) comes first.`, first: first ? first.key : null };
+}
+
+// Which read-only sources suit which step. Names are the keys of SOURCE_MCP below.
+const STEP_SOURCES = {
+  route: ['jira', 'slack'], understand: ['wispr', 'confluence', 'jira', 'slack'], spec: ['wispr', 'confluence', 'jira', 'gmail'],
+  priors: ['confluence'], prototype: ['wispr', 'slack'], build: ['jira', 'confluence'], returned: ['wispr', 'slack', 'gmail'],
+  brief: ['wispr', 'calendar', 'gmail'], draft: ['wispr', 'confluence', 'gmail'],
+};
+// MCP server names a profile may declare, per source. A name outside this table names nothing.
+const SOURCE_MCP = {
+  wispr: ['wispr', 'wispr-flow', 'wisprflow'], gmail: ['gmail', 'google-mail'], calendar: ['google-calendar', 'gcal', 'calendar'],
+  confluence: ['confluence', 'atlassian'], jira: ['jira', 'atlassian'], slack: ['slack'],
+};
+const SOURCE_LABEL = { wispr: 'Wispr Flow notes and meetings', gmail: 'Gmail', calendar: 'Google Calendar', confluence: 'Confluence', jira: 'Jira', slack: 'Slack' };
+
+/** The sources the prompt may name: suited to the step AND declared by the chosen profile's `mcp` list. */
+function sourcesFor(item, mcpDeclared) {
+  const declared = new Set((Array.isArray(mcpDeclared) ? mcpDeclared : []).map((s) => String(s).toLowerCase()));
+  const want = STEP_SOURCES[item && item.kind === 'returned' ? 'returned' : item && item.key] || [];
+  return want.filter((s) => (SOURCE_MCP[s] || []).some((n) => declared.has(n))).map((s) => ({ id: s, label: SOURCE_LABEL[s] }));
+}
+
+const RULES = [
+  'Commit only to this local branch, or write draft files in the repository.',
+  'Do not push, open a pull request, send or post anything, create a ticket, record an acceptance, approve a contract, or merge. Those are the PM\'s.',
+  'Do only this step. If you find another problem, write it down and stop.',
+  'When you finish, stop and write a short summary: what you changed, and what you could not verify.',
+];
+
+/**
+ * The exact first input a session would receive.
+ * @param {{initiative:string, title?:string, item:object, branch:string|null, sources:Array, judgment:string}} p
+ */
+function buildPrompt(p) {
+  const it = p.item || {};
+  const lines = [];
+  lines.push(`Work on initiative ${p.initiative}${p.title ? ' — ' + p.title : ''}.`);
+  lines.push(`Step: ${it.key || it.kind}${it.text && it.text !== it.key ? ' — ' + it.text : ''}.`);
+  if (it.action) lines.push(`What is needed: ${it.action}`);
+  if (it.why && it.why !== it.action) lines.push(`Why this step is open: ${it.why}`);
+  lines.push(`You are on ${p.branch ? 'branch ' + p.branch : 'the current branch'}. Read AGENTS.md, then this initiative's record, PRD and rubric in planning/ before you act.`);
+  lines.push('');
+  lines.push('Rules that do not bend:');
+  for (const r of RULES) lines.push('- ' + r);
+  if (p.sources && p.sources.length) {
+    lines.push('');
+    lines.push('You may read these sources for context. They are read-only: look, do not write.');
+    for (const s of p.sources) lines.push('- ' + s.label);
+  }
+  if (p.judgment) { lines.push(''); lines.push(p.judgment); }
+  return lines.join('\n');
+}
+
+/** A short fingerprint of what the PM is shown. Go must carry it back; if anything changed, the start is refused. */
+function planHash(parts) {
+  return crypto.createHash('sha256').update(JSON.stringify([parts.prompt, parts.branch || null, parts.wsId || null, parts.plan || null, !!parts.judgment])).digest('hex').slice(0, 16);
+}
+
+module.exports = { actFor, annotate, refusal, sourcesFor, buildPrompt, planHash, ACT_TYPES, KNOWN_KEYS, WORK_KEYS, GATE_KEYS, RULES, SOURCE_LABEL };

package/workspace/lib/next-steps.js

@@ -19,12 +19,18 @@
 
 const REMAINING = new Set(['blocked', 'current', 'pending', 'unknown']);
 
+// Who acts on a step. Acceptance, the contract approval, a document's approval and an outcome check are the PM's;
+// every other ladder step is the agent's. This is the one place that is decided: later work reads `owner`, it
+// does not re-decide it.
+const PM_STEPS = new Set(['accept', 'contract', 'approved', 'outcome']);
+const slug = (t) => String(t == null ? '' : t).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+
 const clip = (s, n = 200) => String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, n);
 
 function stepItem(s) {
   const unread = s.status === 'unknown';
   return {
-    kind: 'step', key: s.key, status: s.status,
+    kind: 'step', key: s.key, status: s.status, owner: PM_STEPS.has(s.key) ? 'pm' : 'agent', act: null,
     text: unread ? `${s.key} could not be read` : s.key,
     action: clip(s.next || s.evidence || (unread ? 'the workflow engine could not decide this step' : 'no action recorded for this step')),
     why: clip(s.evidence),
@@ -33,6 +39,18 @@ function stepItem(s) {
   };
 }
 
+// A stable id: initiative + kind + the thing it is about (the step key, the session id, the words of an open item).
+function withIds(id, items) {
+  const seen = new Map();
+  for (const it of items) {
+    const tail = it.kind === 'session' ? (it.sid || slug(it.text)) : it.kind === 'needs' ? slug(it.text) : it.key;
+    const base = `${id || 'initiative'}:${it.kind}:${tail}`;
+    const n = (seen.get(base) || 0) + 1; seen.set(base, n);
+    it.id = n > 1 ? `${base}:${n}` : base;
+  }
+  return items;
+}
+
 function deriveNextSteps(input) {
   const i = input || {};
   const row = i.ladder && i.ladder.ok && i.ladder.row ? i.ladder.row : null;
@@ -49,12 +67,13 @@ function deriveNextSteps(input) {
   const stopped = i.lifecycle && i.lifecycle.state && i.lifecycle.state !== 'active' ? i.lifecycle : null;
   if (stopped) {
     const items = [{
-      kind: 'reopen', key: 'reopen', status: 'pending',
+      kind: 'reopen', key: 'reopen', status: 'pending', owner: 'pm', act: null,
       text: `Reopen — it is ${stopped.state}`,
       action: 'Reopen it to put it back on the board and have its steps gate again. Nothing below is required while it is stopped.',
       why: clip(stopped.reason), source: 'lifecycle.jsonl (D70)',
     }, ...ordered.map((s) => ({ ...stepItem(s), held: true }))];
     items.forEach((it, n) => { it.n = n + 1; it.first = n === 0; });
+    withIds(i.id, items);
     return {
       state: 'stopped',
       summary: `Stopped (${stopped.state})${stopped.reason ? ' — ' + clip(stopped.reason, 120) : ''}. It is off the board and not gating. Reopen to continue; the steps it would then owe are listed after.`,
@@ -73,26 +92,26 @@ function deriveNextSteps(input) {
   const hasAcceptStep = steps.some((s) => s.key === 'accept');
   for (const n of (i.needs || [])) {
     items.push({
-      kind: 'needs', key: 'needs', status: 'pending', text: clip(n.question || '(unstated)', 160),
+      kind: 'needs', key: 'needs', status: 'pending', owner: 'pm', act: null, text: clip(n.question || '(unstated)', 160),
       action: 'Answer or clear this open item.', why: '', source: 'needs queue',
     });
   }
   if (i.returned) {
     items.push({
-      kind: 'returned', key: 'returned', status: 'blocked', text: 'The PM returned this at the Acceptance Gate',
+      kind: 'returned', key: 'returned', status: 'blocked', owner: 'pm', act: null, text: 'The PM returned this at the Acceptance Gate',
       action: 'Address the return, then request acceptance again.', why: '', source: 'acceptances.jsonl',
     });
   }
   for (const s of live) {
     items.push({
-      kind: 'session', key: 'session', status: 'current', text: `Session “${clip(s.name, 60)}” is running on it`,
+      kind: 'session', key: 'session', status: 'current', owner: 'agent', act: null, sid: s.id || null, text: `Session “${clip(s.name, 60)}” is running on it`,
       action: 'Let it finish, or end it before accepting.', why: '', source: 'live sessions',
     });
   }
-  if (acceptStep) items.push({ ...stepItem(acceptStep), kind: 'accept', text: 'PM Acceptance' });
+  if (acceptStep) items.push({ ...stepItem(acceptStep), kind: 'accept', owner: 'pm', text: 'PM Acceptance' });
   else if (!hasAcceptStep) {
     items.push({
-      kind: 'accept', key: 'accept', status: 'pending', text: 'PM Acceptance',
+      kind: 'accept', key: 'accept', status: 'pending', owner: 'pm', act: null, text: 'PM Acceptance',
       action: 'The PM names one thing verified by hand, then records the acceptance (D12). It is the PM’s and cannot be delegated.',
       why: '', source: 'Acceptance Gate (D12)',
     });
@@ -101,6 +120,7 @@ function deriveNextSteps(input) {
   const engineNext = row.next && row.next.step ? row.next.step : null;
   const firstIdx = engineNext ? Math.max(0, items.findIndex((x) => x.kind === 'step' && x.key === engineNext)) : 0;
   items.forEach((it, n) => { it.n = n + 1; it.first = n === firstIdx; });
+  withIds(i.id, items);
   if (!items.length) return { state: 'open', summary: 'No step is outstanding — the ladder shows every required step done. Acceptance is the PM’s.', items: [] };
   const blockedN = items.filter((x) => x.status === 'blocked').length;
   return {

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,119 @@
+'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') : [],
+  };
+}
+
+function setRepo(stateDir, root, { consent, exclude }) {
+  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 } };
+  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 };

package/workspace/lib/typesafe.js

@@ -0,0 +1,124 @@
+'use strict';
+/* typesafe.js — the ONE place the workspace server makes an outbound request (D79).
+ *
+ * D69, D70 and D71 say the PMOS server makes no outbound request. D79 narrows that by one named
+ * exception: HTTPS to `api.typesafe.ai`, from this module, and nowhere else. Three properties keep the
+ * exception small, and each has a test:
+ *
+ *   1. ONE HOST, FIXED IN SOURCE. The host is a constant. No argument, setting or environment variable
+ *      names it. A response that redirects is REFUSED, not followed, because a redirect is how a fixed
+ *      host becomes another host.
+ *   2. THE KEY LEAVES THIS PROCESS IN ONE HEADER. It is an argument to `ask`, never stored here, never
+ *      placed in an error, a log line or a returned object.
+ *   3. NO KEY, NO REQUEST. `ask` refuses before opening a socket when the key is absent.
+ *
+ * What Jev is: a classifier. The caller sends text (`state`) and typed questions; it returns answers
+ * with probabilities. It reads no files and takes no action — the caller reads the files.
+ *   Noul    "high means yes"; the single `noul` number is P(yes). There is no separate confidence.
+ *   Score   levels 0..N-1; `score` is the probability-weighted mean; `confidence` is reported.
+ *   Choice  one option plus a distribution.
+ */
+const https = require('https');
+const http = require('http');
+
+const HOST = 'api.typesafe.ai';
+const PATH = '/v1/systemone';
+const DEFAULT_MODEL = 'jev-latest';
+const MAX_STATE_CHARS = 60000;       // a conservative cap; the documentation states no limit
+const MAX_RESPONSE_BYTES = 1 << 20;  // 1 MiB — an answer set is small; anything larger is not one
+const MAX_QUESTIONS = 16;
+
+/* A seam for tests, gated like the sink's. It lets a suite point this module at a loopback stub; it
+ * is unreachable in a production process, so no setting can redirect the key to another host. */
+let endpointForTests = null;
+function __setEndpointForTests(e) {
+  const on = (v) => v === '1' || v === 'true' || v === 'yes';
+  if (process.env.NODE_ENV !== 'test' && !on(process.env.PMOS_TEST)) {
+    throw new Error('__setEndpointForTests is a test seam — set NODE_ENV=test or PMOS_TEST=1 to use it');
+  }
+  endpointForTests = e || null;
+}
+function endpoint() {
+  return endpointForTests || { protocol: 'https:', hostname: HOST, port: 443 };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const retryable = (status) => status === 429 || status === 529 || (status >= 500 && status < 600);
+
+function validKey(key) {
+  return typeof key === 'string' && key.length >= 8 && key.length <= 512 && !/[\s\u0000-\u001f\u007f]/.test(key);
+}
+
+function once({ key, body, timeoutMs }) {
+  const ep = endpoint();
+  const mod = ep.protocol === 'http:' ? http : https;
+  const payload = Buffer.from(body, 'utf8');
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+    const req = mod.request({
+      protocol: ep.protocol, hostname: ep.hostname, port: ep.port, path: PATH, method: 'POST',
+      headers: {
+        'Content-Type': 'application/json', 'Content-Length': payload.length,
+        Authorization: 'Bearer ' + key, 'User-Agent': 'pmos-workspace',
+      },
+      timeout: timeoutMs,
+    }, (res) => {
+      const status = res.statusCode || 0;
+      // Refused, not followed: the host is fixed in source and a redirect would change it.
+      if (status >= 300 && status < 400) { res.resume(); return finish({ ok: false, status, reason: 'the service sent a redirect, which is refused' }); }
+      const chunks = []; let size = 0;
+      res.on('data', (c) => {
+        size += c.length;
+        if (size > MAX_RESPONSE_BYTES) { finish({ ok: false, status, reason: 'the response was larger than expected and was dropped' }); req.destroy(); return; }
+        chunks.push(c);
+      });
+      res.on('end', () => {
+        let json = null;
+        try { json = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { /* not JSON */ }
+        if (status >= 200 && status < 300 && json && typeof json.answers === 'object' && json.answers) {
+          return finish({ ok: true, status, model: String(json.model || ''), answers: json.answers, usage: json.usage || null });
+        }
+        const why = status === 401 ? 'the service rejected the key (401)'
+          : status === 422 ? 'the service rejected the request as malformed (422)'
+          : status === 429 ? 'the service rate-limited the request (429)'
+          : status === 529 ? 'the service is overloaded (529)'
+          : `the service answered ${status || 'with something unreadable'}`;
+        finish({ ok: false, status, reason: why });
+      });
+      res.on('error', () => finish({ ok: false, status, reason: 'the connection broke while reading the answer' }));
+    });
+    req.on('timeout', () => { finish({ ok: false, status: 0, reason: 'the service did not answer in time' }); req.destroy(); });
+    req.on('error', (e) => finish({ ok: false, status: 0, reason: 'the service could not be reached (' + String((e && e.code) || 'network error') + ')' }));
+    req.end(payload);
+  });
+}
+
+/**
+ * Ask Jev typed questions about `state`.
+ *
+ * @param {object} a
+ * @param {string} a.key        the API key. Required; no key means no request.
+ * @param {string} a.state      the text to judge. Refused above MAX_STATE_CHARS.
+ * @param {object} a.questions  { name: { type: 'noul'|'score'|'choice', instructions, criteria? } }
+ * @returns {Promise<{ok:true, model, answers, usage}|{ok:false, reason, status?, requested:boolean}>}
+ *   `requested` says whether a request left this process, so a caller can tell a refusal from a failure.
+ */
+async function ask({ key, state, questions, model = DEFAULT_MODEL, timeoutMs = 30000, retries = 2, backoffMs = 600 } = {}) {
+  if (!validKey(key)) return { ok: false, requested: false, reason: 'no TypeSafe key is set' };
+  if (typeof state !== 'string' || !state.trim()) return { ok: false, requested: false, reason: 'there is no text to judge' };
+  if (state.length > MAX_STATE_CHARS) return { ok: false, requested: false, reason: `the text is longer than ${MAX_STATE_CHARS} characters` };
+  const names = questions && typeof questions === 'object' ? Object.keys(questions) : [];
+  if (!names.length || names.length > MAX_QUESTIONS) return { ok: false, requested: false, reason: `between 1 and ${MAX_QUESTIONS} questions are required` };
+  const body = JSON.stringify({ state, model, questions });
+  let last = null;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    last = await once({ key, body, timeoutMs });
+    if (last.ok) return { ...last, requested: true };
+    if (!(last.status === 0 || retryable(last.status)) || attempt === retries) break;
+    await sleep(backoffMs * Math.pow(2, attempt));
+  }
+  return { ok: false, requested: true, status: last.status, reason: last.reason };
+}
+
+module.exports = { ask, validKey, HOST, PATH, DEFAULT_MODEL, MAX_STATE_CHARS, MAX_QUESTIONS, __setEndpointForTests };