create-pmos 0.38.7 → 0.39.0

package/workspace/lib/schedule-logic.js

@@ -86,10 +86,25 @@ function nextSlot(schedule, now) {
 }
 function addDays(d, n) { const x = new Date(d); x.setDate(x.getDate() + n); return x; }
 
+// R5 — an optional end. A schedule ends when it has run `max_runs` times or when the day after `until` begins
+// (the `until` day itself still runs). No `until` and no `max_runs` means it never ends on its own.
+function endOfDay(dateStr) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(dateStr || ''));
+  return m ? new Date(+m[1], +m[2] - 1, +m[3] + 1, 0, 0, 0, 0) : null;
+}
+function finishReason(schedule, now = new Date()) {
+  if (!schedule) return null;
+  const max = +schedule.max_runs;
+  if (max > 0 && (+schedule.runs || 0) >= max) return `max_runs reached (${max} run${max === 1 ? '' : 's'})`;
+  const end = endOfDay(schedule.until);
+  if (end && now >= end) return `until ${schedule.until} has passed`;
+  return null;
+}
 // Is the schedule due to fire at `now`? Enabled + a slot in (lastRun, now]. For bi-weekly, also
 // require ≥ 13 days since lastRun (weekly slots, fired every other week).
 function isDue(schedule, now = new Date()) {
   if (!schedule || !schedule.enabled) return false;
+  if (finishReason(schedule, now)) return false;
   const slot = lastSlot(schedule, now);
   if (!slot) return false;
   const last = schedule.lastRun ? new Date(schedule.lastRun) : null;
@@ -130,6 +145,11 @@ function normalizeSchedule(input) {
   if (!s.name || !String(s.name).trim()) return { ok: false, error: 'name is required' };
   if (!CADENCES.includes(s.cadence)) return { ok: false, error: 'invalid cadence' };
   if (!s.skill || !String(s.skill).trim()) return { ok: false, error: 'a skill-backed task is required' };
+  if (s.until != null && s.until !== '') {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(String(s.until)) || !endOfDay(s.until) || Number.isNaN(endOfDay(s.until).getTime())) return { ok: false, error: 'until must be a date, YYYY-MM-DD' };
+    if (endOfDay(s.until) <= new Date()) return { ok: false, error: 'until is already in the past — the schedule would never run' };
+  }
+  if (s.max_runs != null && s.max_runs !== '' && !(Number.isInteger(+s.max_runs) && +s.max_runs >= 1 && +s.max_runs <= 10000)) return { ok: false, error: 'max_runs must be a whole number from 1 to 10000' };
   if (s.cadence === 'once') {
     if (!/^\d{4}-\d{2}-\d{2}$/.test(String(s.date || ''))) return { ok: false, error: 'a one-off needs a date (YYYY-MM-DD)' };
     const slot = onceSlot({ date: s.date, time: s.time });
@@ -153,9 +173,11 @@ function normalizeSchedule(input) {
       task: s.task || s.skill,
       skill: String(s.skill).trim(),
       enabled: s.enabled !== false,
+      ...(s.until ? { until: String(s.until) } : {}),
+      ...(s.max_runs ? { max_runs: Math.floor(+s.max_runs) } : {}),
     },
   };
 }
 function parseTimeStr(t) { const { h, m } = parseTime(t); return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`; }
 
-module.exports = { CADENCES, isMissed, ONCE_GRACE_MS, isDue, nextRun, humanCadence, normalizeSchedule, lastSlot, nextSlot };
+module.exports = { finishReason, endOfDay, CADENCES, isMissed, ONCE_GRACE_MS, isDue, nextRun, humanCadence, normalizeSchedule, lastSlot, nextSlot };

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/skill-store.js

@@ -266,7 +266,7 @@ function retargetFiling(text, filing) {
 // Scaffold a well-formed user skill file from the New Skill flow's fields. Returns { ok, slug, content }
 // or { ok:false, error }. User skills default to run:agent — a user-authored skill reasons through a
 // claude session (the existing agent path); the deterministic fast-path is reserved for the built-ins.
-function scaffoldSkill({ name, description, output, body, filing } = {}) {
+function scaffoldSkill({ name, description, output, body, filing, work } = {}) {
   const slug = slugify(name);
   if (!NAME_RE.test(slug)) return { ok: false, error: 'name must be a short slug (letters, digits, hyphens)' };
   const label = titleCase(name) || slug;
@@ -276,7 +276,7 @@ function scaffoldSkill({ name, description, output, body, filing } = {}) {
   if (!out.length) out = ['Summary', 'Findings', 'Next steps'];   // always a valid contract
   // A hand-written body is retargeted too: a PM pasting the old contract text in gets a skill that
   // files where the console reads, not one that quietly writes into a directory nobody opens.
-  const proc = retargetFiling(String(body || '').trim(), filing) || defaultBody(label, desc, out, slug, filing);
+  const proc = retargetFiling(String(body || '').trim(), filing) || defaultBody(label, desc, out, slug, filing, work ? String(work).slice(0, 8000) : null);
   const content = [
     '---',
     `name: ${slug}`,
@@ -306,7 +306,7 @@ function scaffoldSkill({ name, description, output, body, filing } = {}) {
 // suite could not reach it. A scaffold that still said "workspace/state/deliverables/" would send
 // every scheduled agent's report to a directory the console never reads: a silent, permanent
 // no-show in the needs-you queue. The defaults keep this module usable standalone.
-function defaultBody(label, desc, out, slug, filing) {
+function defaultBody(label, desc, out, slug, filing, work) {
   const id = slug || slugify(label) || 'run';
   const deliverables = (filing && filing.deliverables) || 'workspace/state/deliverables';
   const needs = (filing && filing.needs) || 'workspace/state/needs.json';
@@ -318,9 +318,17 @@ function defaultBody(label, desc, out, slug, filing) {
     '',
     'Procedure — run the numbered steps in order; each ends on a checkable done-condition:',
     '',
+    ...(work ? [
+      '1. Repeat the work below. It was captured from an earlier terminal session by the PM: do the same job again,',
+      "   with today's dates and this repository's current files. Do not repeat one-off details (old names, old dates, old errors).",
+      '   Done when: the same kind of result exists for today, each statement traceable to a real source.',
+      '   Captured work:',
+      ...String(work).split('\n').map((l) => '   | ' + l),
+    ] : [
     "1. Gather inputs from this repo's own local sources — name the exact commands/paths the run",
     '   depends on (e.g. `git log`, `gh pr view <n> --json title,body`, a file under `planning/`).',
     '   Done when: every input the sections below need is in hand, each traceable to a real source.',
+    ]),
     '2. Produce each required section from those inputs, in the exact order of the output contract.',
     '   An empty section is the literal line "None this period." — never a dropped heading, never invented content.',
     '   Done when: every contract section is filled or explicitly "None this period.".',

package/workspace/lib/status-groups.js

@@ -0,0 +1,109 @@
+'use strict';
+// Grouping the initiative list by status (initiative-surface-batch R2).
+//
+// The status is not typed by anyone: the server derives it for every initiative from the ledgers and
+// git (`deriveState` in server.js — stopped, accepted, blocked, delivered, building, planning, unknown)
+// and, for a stopped one, the lifecycle ledger says which kind (on-hold, closed, cancelled). This maps
+// that derived pair to the PM's words and puts the groups in one order. It reads the derived value and
+// nothing else, so a hand-typed `status:` in a record can never decide where a row lands, and an
+// unreadable history is its own group instead of passing for Planning.
+//
+// Classic script (a UMD setting window.PMOSStatusGroups) like the other lib/ files the board shares
+// with node, so the order and the mapping are walkable in the test suite.
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== 'undefined' && module.exports) module.exports = api;
+  else root.PMOSStatusGroups = api;
+}(typeof self !== 'undefined' ? self : this, function () {
+
+  // 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',
+      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. */
+  function keyOf(row) {
+    if (!row || typeof row !== 'object') return 'unknown';
+    switch (row.status) {
+      case 'blocked': return 'needs-you';
+      case 'building': return 'in-progress';
+      case 'planning': return 'planning';
+      case 'delivered': return 'awaiting-acceptance';
+      case 'accepted': return 'accepted';
+      case 'stopped': {
+        const s = row.lifecycle && row.lifecycle.state;
+        return s === 'on-hold' || s === 'closed' || s === 'cancelled' ? s : 'unknown';
+      }
+      default: return 'unknown';
+    }
+  }
+
+  /**
+   * @param {string[]} slugs               every initiative on the board
+   * @param {Object<string,Object>} rows   slug → derived status row (missing → Unknown)
+   * @param {{activeOnly?:boolean}} opts
+   * @returns {Array<{key,label,hint,active,slugs:string[]}>} non-empty groups only, in order
+   */
+  function group(slugs, rows, opts) {
+    const activeOnly = !!(opts && opts.activeOnly);
+    const buckets = new Map(GROUPS.map((g) => [g.key, []]));
+    for (const slug of slugs || []) buckets.get(keyOf(rows && rows[slug])).push(slug);
+    return GROUPS.filter((g) => (!activeOnly || g.active) && buckets.get(g.key).length)
+      .map((g) => ({ ...g, slugs: buckets.get(g.key) }));
+  }
+
+  return { GROUPS, BY_KEY, LEGEND_FIELDS, keyOf, group };
+}));

package/workspace/lib/transcripts.js

@@ -0,0 +1,73 @@
+'use strict';
+/* transcripts.js — the record of a conversation that belongs to an initiative.
+ *
+ * A session's terminal text used to live and die with the session: removing it deleted the only copy,
+ * so an initiative's discussion could not be reviewed later. A session that belongs to an initiative is
+ * now saved here when it ends or is removed, and listed beside the initiative's other artifacts.
+ *
+ * WHERE: one JSON file per session under `<runtime state>/transcripts/`. The runtime state directory is
+ * machine-local and outside every repository (lib/state-root.js). A transcript can hold anything the PM
+ * typed or an agent printed — including a secret — so it is deliberately NOT written into the repository
+ * (PM ruling 2026-10-03) and is never sent anywhere. Pure of the network (D54): fs only.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const MAX_CHARS = 400000;           // the tail of a very long session; the record says when it was cut
+const ID_RE = /^[A-Za-z0-9._-]+$/;
+
+// Terminal text without its escape sequences: colours, cursor moves, the window-title and hyperlink codes.
+function stripAnsi(text) {
+  return String(text == null ? '' : text)
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '')
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')
+    .replace(/\x1b[()][A-Za-z0-9]/g, '')
+    .replace(/\r(?!\n)/g, '\n').replace(/\r/g, '');
+}
+
+const dirOf = (stateDir) => path.join(stateDir, 'transcripts');
+const fileOf = (stateDir, id) => path.join(dirOf(stateDir), id + '.json');
+
+/** Write (or refresh) one session's record. Returns {ok, path} or {ok:false, error}; never throws. */
+function save(stateDir, rec) {
+  try {
+    const id = String(rec && rec.id || '');
+    if (!ID_RE.test(id)) return { ok: false, error: 'not a session id' };
+    if (!rec.initiative || !ID_RE.test(String(rec.initiative))) return { ok: false, error: 'the session is on no initiative — nothing to record' };
+    const full = stripAnsi(rec.text);
+    const cut = full.length > MAX_CHARS;
+    const out = {
+      id, name: String(rec.name || id).slice(0, 80), agent: rec.agent || null, ws: rec.ws || null,
+      initiative: String(rec.initiative), state: rec.state || 'exited',
+      started: rec.started || null, saved: rec.saved || new Date().toISOString(),
+      cut, chars: Math.min(full.length, MAX_CHARS), text: cut ? full.slice(-MAX_CHARS) : full,
+    };
+    fs.mkdirSync(dirOf(stateDir), { recursive: true });
+    const file = fileOf(stateDir, id);
+    fs.writeFileSync(file + '.tmp', JSON.stringify(out));
+    fs.renameSync(file + '.tmp', file);
+    return { ok: true, path: file };
+  } catch (e) { return { ok: false, error: String((e && e.message) || e).slice(0, 160) }; }
+}
+
+function read(stateDir, id) {
+  if (!ID_RE.test(String(id || ''))) return null;
+  try { return JSON.parse(fs.readFileSync(fileOf(stateDir, id), 'utf8')); } catch { return null; }
+}
+
+/** Every saved record for one initiative, newest first, without the text. */
+function listFor(stateDir, initiative) {
+  let names = [];
+  try { names = fs.readdirSync(dirOf(stateDir)); } catch { return []; }
+  const out = [];
+  for (const n of names) {
+    if (!n.endsWith('.json')) continue;
+    let r = null;
+    try { r = JSON.parse(fs.readFileSync(path.join(dirOf(stateDir), n), 'utf8')); } catch { continue; }
+    if (!r || r.initiative !== initiative) continue;
+    out.push({ id: r.id, name: r.name, ws: r.ws, state: r.state, started: r.started, saved: r.saved, chars: r.chars, cut: !!r.cut });
+  }
+  return out.sort((a, b) => String(b.saved).localeCompare(String(a.saved)));
+}
+
+module.exports = { stripAnsi, save, read, listFor, dirOf, MAX_CHARS };

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 };