create-pmos 0.47.0 → 0.49.0

package/workspace/server.js

@@ -20,6 +20,12 @@
  * under state/ (the reconcile seam). Request headers are never logged (D08).
  */
 'use strict';
+// The workspace reads git in the background (repo-watch, git-info, claims), and a plain `git status` takes the index lock to
+// refresh the index. A press that writes, such as Sync's `git add`, then fails on `index.lock: File exists` when the two
+// meet. With optional locks off, the server's reads never take that lock. Set only when the PM has not set it, and taken back
+// out of every terminal session's environment (sessionEnv), so the PM's own shells and agents are unchanged.
+const SET_GIT_OPTIONAL_LOCKS = process.env.GIT_OPTIONAL_LOCKS === undefined;
+if (SET_GIT_OPTIONAL_LOCKS) process.env.GIT_OPTIONAL_LOCKS = '0';
 const http = require('http');
 const fs = require('fs');
 const os = require('os');
@@ -65,9 +71,16 @@ const { createSinkGuard } = require('./lib/sink.js');
 const tsSettings = require('./lib/typesafe-settings.js');
 const sessionFlag = require('./lib/session-flag');   // PMOS_WORKSPACE=1 in each agent terminal (cockpit mod, M12)
 const tsClient = require('./lib/typesafe.js');
+const jevRoute = require('./lib/jev-route.js');     // prompt-model-routing — the bridge between prompt routing and the one TypeSafe module
 const jevClaims = require('./lib/jev-claims.js');   // D80 — the bridge between the claims ledger and the one TypeSafe module
+const jevCategorize = require('./lib/jev-categorize.js');   // D82 — the bridge between the document categorizer and the one TypeSafe module
 const validateLib = require('./lib/validate.js');
+const liveNotes = require('./lib/live-notes.js');   // jev-live-notes — reads and appends a repository's live-notes ledger; no network
+const jevLive = require('./lib/jev-live.js');      // jev-live-notes Run 7 (D85) — the live view's one bridge to Jev, behind three gates
 const claimsLib = require('./lib/claims.js');
+const docCategory = require('./lib/doc-category.js');   // jev-doc-categorizer Run 1 — the PM-facing kind of a document, derived, local, no model
+const docCatCorrections = require('./lib/doc-category-corrections.js');   // jev-doc-categorizer Run 3 — the PM's own category, per user, outside the repository
+const docCatWriteback = require('./lib/doc-category-writeback.js');       // …and the separate press that writes it into the file's frontmatter
 const repoWatch = require('./lib/repo-watch.js');
 tsSettings.adoptEnv(process.env);   // D79 — take the env key into memory and delete it, before anything is spawned
 const scheduleLogic = require('./lib/schedule-logic');
@@ -278,6 +291,11 @@ function sessionEnv() {
   // D79 — the TypeSafe key is the workspace server's own credential. A terminal runs an agent that can
   // print its environment, so the key is never handed to one, whether it came from settings or the shell.
   delete env[tsSettings.ENV_NAME];
+  if (SET_GIT_OPTIONAL_LOCKS) delete env.GIT_OPTIONAL_LOCKS;
+  // prompt-model-routing Run 3 — where the cockpit mod asks for a prompt's route: this server, on loopback.
+  // An address only; the Jev key stays here (D79).
+  const routeUrl = jevRoute.routeUrl(PORT);
+  if (routeUrl) env.PMOS_ROUTE_URL = routeUrl; else delete env.PMOS_ROUTE_URL;
   return env;
 }
 
@@ -457,6 +475,12 @@ function homeWorkspace() {
   return HOME_ENABLED ? workspaces.get(wsId(SELF_ROOT)) : [...workspaces.values()][0];
 }
 function getWs(id) { return (id && workspaces.get(id)) || homeWorkspace(); }
+/** The registered workspace whose root is this path exactly, or null. Never the home workspace by default. */
+function wsByRoot(root) {
+  const want = path.resolve(String(root));
+  for (const w of workspaces.values()) if (w && path.resolve(w.root) === want) return w;
+  return null;
+}
 // R2/R3 — what the sidebar tree needs and cannot derive for itself: which REPOSITORY a registered
 // working tree belongs to, and which branch it is on. `git worktree list` names the main worktree
 // first from any of a repo's trees (git-info.worktreesAt), so index 0 is the group key: it is what
@@ -1536,6 +1560,85 @@ function stampEdit(text, at) {
   const next = fm.replace(re, `generated: {by: human:wawan, at: "${at}"}`);
   return next === fm ? text : text.replace(fm, () => next);
 }
+// ── Document category (jev-doc-categorizer Run 1) ───────────────────────────────────────────────────
+// A derived label beside the document's own `type`: local rules only, no model, nothing written. The library lists it with the
+// basis that decided it, so the PM can see why. A file is read once per modification; only its first 16 KB is needed, because
+// the evidence is the frontmatter, the name and the headings.
+const catCache = new Map();
+function categoryInput(full) {
+  let st; try { st = fs.statSync(full); } catch { return null; }
+  const hit = catCache.get(full);
+  if (hit && hit.m === st.mtimeMs) return hit;
+  let text = '';
+  try { const fd = fs.openSync(full, 'r'); const buf = Buffer.alloc(16384); const n = fs.readSync(fd, buf, 0, 16384, 0); fs.closeSync(fd); text = buf.slice(0, n).toString('utf8'); } catch { return null; }
+  let fm = {}; try { fm = relatedDocs.frontmatter(text) || {}; } catch { /* no frontmatter */ }
+  const ent = { m: st.mtimeMs, fm, text };
+  catCache.set(full, ent);
+  return ent;
+}
+function namedRecords(root) {
+  const records = [];
+  for (const rel of ['planning/initiatives', 'pmos/state/initiatives', 'state/initiatives']) {
+    const d = path.join(root, ...rel.split('/'));
+    let names = []; try { names = fs.readdirSync(d).filter((f) => f.endsWith('.md')); } catch { continue; }
+    for (const f of names) { const c = categoryInput(path.join(d, f)); if (c) records.push({ rel: rel + '/' + f, fm: c.fm }); }
+  }
+  return docCategory.namedFromRecords(records);
+}
+// Run 3 (C7) — the PM's corrections for one repository live in the per-user runtime directory, keyed like the claims cache
+// (sha1 of the root), never in the repository.
+function doccatDir(root) { return docCatCorrections.repoDir(STATE, root); }
+// Adds `category`, `category_basis` and `category_why` to every markdown document anywhere in a library answer, and
+// `category_kind` for a ticket. A stored correction is passed in, so it wins with basis `pm correction`; the bases that
+// disagree with the winner come as `category_disagrees`.
+function annotateCategories(root, node, named, corr = {}, seen = new Set()) {
+  if (!node || typeof node !== 'object' || seen.has(node)) return node;
+  seen.add(node);
+  if (Array.isArray(node)) { for (const x of node) annotateCategories(root, x, named, corr, seen); return node; }
+  if (typeof node.path === 'string' && /\.md$/i.test(node.path)) {
+    const c = categoryInput(path.join(root, node.path));
+    if (c) {
+      const rel = node.path.split(path.sep).join('/');
+      const r = docCategory.categorize({ rel, fm: c.fm, text: c.text, named, correction: Object.prototype.hasOwnProperty.call(corr, rel) ? corr[rel] : null });
+      node.category = r.category; node.category_basis = r.basis; node.category_why = r.via;
+      if (r.ticket_kind) node.category_kind = r.ticket_kind;
+      if (r.disagrees.length) node.category_disagrees = r.disagrees;
+    }
+  }
+  for (const k of Object.keys(node)) if (node[k] && typeof node[k] === 'object') annotateCategories(root, node[k], named, corr, seen);
+  return node;
+}
+// ── D82 — Jev's category for a file the local rules leave undetermined ─────────────────────────────────
+// Its state lives beside the corrections, in doccatDir(root): per user, outside the repository.
+// Reads Jev's CACHED answers only; sends nothing. A decided answer becomes the category with the basis `jev`; an unsure one
+// leaves the file `undetermined` and says which two options led. Advisory (D40): nothing downstream reads it as fact.
+function annotateJev(root, node, cache, seen = new Set()) {
+  if (!node || typeof node !== 'object' || seen.has(node)) return node;
+  seen.add(node);
+  if (Array.isArray(node)) { for (const x of node) annotateJev(root, x, cache, seen); return node; }
+  if (node.category === docCategory.UNDETERMINED && typeof node.path === 'string' && /\.md$/i.test(node.path)) {
+    const c = categoryInput(path.join(root, node.path));
+    const l = c ? jevCategorize.lookup(cache, { fm: c.fm, text: c.text }) : null;
+    if (l && l.decided) { node.category = l.category; node.category_basis = 'jev'; node.category_why = l.sentence; if (l.ticket_kind) node.category_kind = l.ticket_kind; }
+    else if (l) { node.category_why = l.sentence; node.category_jev = 'unsure'; }
+  }
+  for (const k of Object.keys(node)) if (node[k] && typeof node[k] === 'object') annotateJev(root, node[k], cache, seen);
+  return node;
+}
+// Every Markdown document the library lists, with what the categorizer needs. Read through the same per-file cache.
+function doccatDocs(root, lib) {
+  const rels = new Set();
+  (function walk(n, seen) {
+    if (!n || typeof n !== 'object' || seen.has(n)) return; seen.add(n);
+    if (Array.isArray(n)) { for (const x of n) walk(x, seen); return; }
+    if (typeof n.path === 'string' && /\.md$/i.test(n.path)) rels.add(n.path.split(path.sep).join('/'));
+    for (const k of Object.keys(n)) if (n[k] && typeof n[k] === 'object') walk(n[k], seen);
+  })(lib, new Set());
+  const docs = [];
+  const corrections = docCatCorrections.get(doccatDir(root));   // C7 — a corrected file is decided, so it is never sent
+  for (const rel of rels) { const c = categoryInput(path.join(root, ...rel.split('/'))); if (c) docs.push({ rel, fm: c.fm, text: c.text, correction: corrections[rel] || null }); }
+  return docs;
+}
 function library(root) {
   const shape = wsShape(root);
   const roots = libraryTree(root);
@@ -1553,7 +1656,8 @@ function library(root) {
   const notes = NOTE_DIRS.map((d) => path.join(root, ...d.split('/'))).filter((d) => isDir(d))
     .map((d) => tree(root, d, {}, 0, { n: TREE_MAX_NODES }))
     .filter((t) => t.dirs.length || t.docs.length);
-  return { shape, roots, initiatives, ungrouped, knowledge, notes, governance: looseDocs(root) };
+  const out = { shape, roots, initiatives, ungrouped, knowledge, notes, governance: looseDocs(root) };
+  return annotateJev(root, annotateCategories(root, out, namedRecords(root), docCatCorrections.get(doccatDir(root))), jevCategorize.readCache(doccatDir(root)));
 }
 
 // ── On-demand surfaces (D60 / the workspace-ondemand-surfaces PRD). ────────────────────────────
@@ -4594,19 +4698,51 @@ async function runClaims(w, { sweep = false } = {}) {
     // D80 — after the local check, and only when all four gates hold (the bridge decides), ask Jev about changed claim pairs.
     if (out.ok) {
       const f = tsSettings.getRepo(STATE, w.root);
-      const jev = await jevClaims.run({ root: w.root, cacheDir, ledgerFile, key: tsSettings.getKey(STATE), flags: f, exclude: f.exclude, changed: out.run ? out.run.changed : null });
+      const jev = await jevClaims.run({ root: w.root, cacheDir, ledgerFile, key: tsSettings.getKey(STATE), flags: f, exclude: f.exclude, changed: out.run ? out.run.changed : null, askOpts: jevModelOpts(w.root) });
       const fresh = claimsLib.readView({ cacheDir, ledgerFile });
       return { ...out, ...fresh, jev };
     }
     return out;
   } finally { claimsRunning.delete(w.root); }
 }
+// prompt-model-routing R11 — the Jev version a PM names in the model policy reaches the claim checks and keys their cache. None named: the module's own default.
+function jevModelOpts(root) { const m = jevRoute.modelFromPolicy(root); return m ? { model: m } : {}; }
 // D80 — what the page needs to explain the Jev switch: which gates hold, and what the last pass did.
 function jevGateInfo(w) {
   const f = tsSettings.getRepo(STATE, w.root);
   const g = jevClaims.gates({ key: tsSettings.status(STATE).present, consent: f.consent, watch: f.watch, jev: f.jev });
   const { cacheDir } = claimsPaths(w);
-  return { switch: f.jev, open: g.open, missing: g.missing, sentence: g.open ? null : jevClaims.gateSentence(g.missing), ...jevClaims.status(cacheDir) };
+  return { switch: f.jev, status_read: f.status_read, open: g.open, missing: g.missing, sentence: g.open ? null : jevClaims.gateSentence(g.missing), ...jevClaims.status(cacheDir) };
+}
+// D85 — the live-notes add route's sender: lib/typesafe.js behind the key, consent and the switch, or none. The key goes to the engine
+// only when the sender does, and never into a response.
+function liveSender(w) {
+  const key = tsSettings.getKey(STATE);
+  const flags = { consent: tsSettings.getRepo(STATE, w.root).consent, live: liveNotes.getSwitch(STATE, w.root).live };
+  const snd = jevLive.senderFor(key, flags, jevModelOpts(w.root));
+  return { key: snd.ask ? key : null, flags, ask: snd.ask, askOpts: snd.askOpts };
+}
+// D85 — what the live-notes view needs to explain its Jev switch. Booleans and sentences only; the key never leaves the store.
+function liveJevInfo(w) {
+  return jevLive.infoFor(tsSettings.status(STATE).present, { consent: tsSettings.getRepo(STATE, w.root).consent, live: liveNotes.getSwitch(STATE, w.root).live });
+}
+// D82 — what the page needs to explain the categorize switch: which gates hold, and what the last pass did.
+const doccatRunning = new Set();
+const doccatAutoAt = new Map();    // root → time of the last automatic pass; at most one a minute
+function doccatInfo(w) {
+  const f = tsSettings.getRepo(STATE, w.root);
+  const g = jevCategorize.gates({ key: tsSettings.status(STATE).present, consent: f.consent, categorize: f.categorize });
+  return { switch: f.categorize, open: g.open, missing: g.missing, sentence: g.open ? null : jevCategorize.gateSentence(g.missing), running: doccatRunning.has(w.root), ...jevCategorize.status(doccatDir(w.root)) };
+}
+// The automatic pass, after a library listing. The bridge checks the three gates and the confirmed first run; this only
+// keeps it to one pass at a time and one a minute, and never makes the listing wait for it.
+function doccatAuto(w, lib) {
+  const f = tsSettings.getRepo(STATE, w.root);
+  if (!f.categorize || doccatRunning.has(w.root) || Date.now() - (doccatAutoAt.get(w.root) || 0) < 60000) return;
+  doccatAutoAt.set(w.root, Date.now());
+  doccatRunning.add(w.root);
+  jevCategorize.runAuto({ docs: doccatDocs(w.root, lib), named: namedRecords(w.root), cacheDir: doccatDir(w.root), key: tsSettings.getKey(STATE), flags: f, exclude: f.exclude })
+    .catch(() => null).finally(() => doccatRunning.delete(w.root));
 }
 const claimsLast = new Map();      // root → { at, run, error }
 const claimsWatcher = repoWatch.createWatcher({
@@ -5072,7 +5208,9 @@ async function handleRequest(req, res) {
   if (p === '/api/library') {
     const w = getWs(url.searchParams.get('ws'));
     if (!w) return json(res, { ws: null, shape: 'plain', roots: [], initiatives: [], ungrouped: [], knowledge: [], governance: [] });
-    return json(res, { ws: w.id, ...library(w.root) });
+    const lib = library(w.root);
+    doccatAuto(w, lib);                 // D82 — in the background, and only when the three gates hold and the first run was confirmed
+    return json(res, { ws: w.id, ...lib, doccat: doccatInfo(w) });
   }
   if (p === '/api/surface') {
     // On-demand P/D/M/R surface, derived through the local state adapter only (no network).
@@ -5427,6 +5565,38 @@ async function handleRequest(req, res) {
     let md; try { md = fs.readFileSync(path.join(DELIV_DIR, id + '.md'), 'utf8'); } catch { res.writeHead(404); return res.end('not found'); }
     res.writeHead(200, { 'Content-Type': 'text/markdown; charset=utf-8' }); return res.end(md);
   }
+  // ── prompt-model-routing — route ANY prompt to a tier. A SUGGESTION: nothing here starts, switches or types into a session. ──
+  if (p === '/api/model/route/switch' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws); if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    if (typeof body.route !== 'boolean') return json(res, { ok: false, error: 'route must be true or false' }, 400);
+    const out = tsSettings.setRepo(STATE, w.root, { route: body.route });
+    if (!out.ok) return json(res, { ok: false, error: out.error }, 500);
+    const f = tsSettings.getRepo(STATE, w.root);
+    const g = jevRoute.gates({ key: tsSettings.status(STATE).present, consent: f.consent, route: f.route });
+    return json(res, { ok: true, ws: w.id, route: f.route, open: g.open, missing: g.missing, sentence: g.open ? null : jevRoute.gateSentence(g.missing) });
+  }
+  if (p === '/api/model/route' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    // A terminal's cockpit mod names its repository by root; the page names a workspace by id.
+    const w = typeof body.root === 'string' ? wsByRoot(body.root) : getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace for that repository' }, 400);
+    if (typeof body.prompt !== 'string' || !body.prompt.trim() || body.prompt.length > 60000) return json(res, { ok: false, error: 'prompt must be text of up to 60000 characters' }, 400);
+    const f = tsSettings.getRepo(STATE, w.root);
+    const out = await jevRoute.routePrompt({ root: w.root, prompt: body.prompt, ctx: { skill: typeof body.skill === 'string' ? body.skill : undefined, source: body.source, running: true },
+      key: tsSettings.getKey(STATE), flags: { consent: f.consent, route: f.route, exclude: f.exclude }, askOpts: body.interactive === true ? jevRoute.INTERACTIVE : {} });
+    if (!out.ok) return json(res, { ok: false, error: out.error }, 400);
+    if (out.shadow) return json(res, { ok: true, shadow: true, id: out.id });             // shadow: logged, nothing shown, nothing applied
+    return json(res, { ok: true, ws: w.id, id: out.id, tier: out.tier, model: out.model, effort: out.effort, stage: out.stage, confidence: out.confidence, why: out.why,
+      applies: out.applies, sent: out.sent, withheld: out.withheld ? out.withheld.why : null, gate: out.gate });
+  }
+  if (p === '/api/model/route/outcome' && req.method === 'POST') {
+    let body = {}; try { body = JSON.parse((await readBody(req)) || '{}'); } catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws); if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const mc = modelLib.core(); if (!mc.ok) return json(res, { ok: false, error: mc.error }, 500);
+    if (!mc.core.attachOutcome(w.root, body.id, { outcome: body.outcome, applied_tier: body.tier })) return json(res, { ok: false, error: 'an id from a routed prompt and an outcome of ' + mc.core.OUTCOMES.join(', ') + ' are needed (and the decisions ledger opted in)' }, 400);
+    return json(res, { ok: true });
+  }
   if (p === '/api/session/model' && req.method === 'POST') {
     // D75 — switch the model of a RUNNING Claude session, on the PM's press only. It types the harness's own
     // `/model <model>` command into the pane; effort is not changed by it. Never automatic, never for a binary
@@ -5740,7 +5910,12 @@ async function handleRequest(req, res) {
     try { nextStepActions.annotate(nextSteps, (it) => nextStepPathOf(root, it)); attachRuns(nextSteps, id); } catch (e) { void e; }
     let lcHistory = [];
     try { lcHistory = lifecycleHistory(w, id); } catch { lcHistory = []; }
-    return json(res, { ws: w ? w.id : null, ...out, lanes, conversations, files, next_steps: nextSteps, lifecycle_history: lcHistory });
+    // D83 — what Jev suggests about the documents tied to this initiative, read from the claims ledger. Advisory: the
+    // panel shows it beside the ladder and nothing derives a step, a stage or a count from it.
+    let suggestions = null;
+    try { if (w) suggestions = jevClaims.suggestionsFor({ ledgerFile: claimsPaths(w).ledgerFile, initiativeId: id }); }
+    catch { suggestions = { ok: false, reason: 'the suggestions could not be read', items: [] }; }
+    return json(res, { ws: w ? w.id : null, ...out, lanes, conversations, files, next_steps: nextSteps, lifecycle_history: lcHistory, suggestions });
   }
   if (p === '/api/audit' && req.method === 'GET') {
     /* The workflow audit (D77): the sweep run on one repository, read-only. It reports state that contradicts
@@ -6231,6 +6406,62 @@ async function handleRequest(req, res) {
     if (!out.ok) return json(res, { ok: false, error: out.error }, 500);
     return json(res, { ok: true, ws: w.id, watching: tsSettings.getRepo(STATE, w.root).watch === true });
   }
+  // ── jev-doc-categorizer Run 3 (C7) — the PM corrects a category, and may write it into the file ─────────────────────
+  // A correction is per-user state OUTSIDE the repository and never edits a file. The write-back is a separate press with
+  // two steps — the diff first, then a confirmed write that names the sha1 of the text the PM saw — and it is the ONLY
+  // write into the repository on this surface.
+  if (p === '/api/doccat/corrections' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    return json(res, { ok: true, ws: w.id, corrections: docCatCorrections.get(doccatDir(w.root)) });
+  }
+  if ((p === '/api/doccat/correct' || p === '/api/doccat/writeback') && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    // Path guard: the store's own check (relative, no `..`, Markdown only), then the same inside-the-workspace rule every
+    // read and write on this surface uses, then the real path, so a symlink cannot lead out of the repository.
+    const chk = docCatCorrections.checkRel(body.path);
+    if (chk.error) return json(res, { ok: false, error: chk.error }, 400);
+    const rel = chk.rel;
+    const full = path.resolve(w.root, ...rel.split('/'));
+    if (!insideRoot(w.root, full)) return json(res, { ok: false, error: 'outside workspace' }, 404);
+    let lst = null; try { lst = fs.lstatSync(full); } catch { /* reported below */ }
+    if (!lst) return json(res, { ok: false, error: 'There is no such document in this repository.' }, 404);
+    let real = null; try { real = fs.realpathSync(full); } catch { /* reported below */ }
+    let realRoot = w.root; try { realRoot = fs.realpathSync(w.root); } catch { /* keep the root as given */ }
+    if (!real || !insideRoot(realRoot, real)) return json(res, { ok: false, error: 'outside workspace' }, 404);
+    const dir = doccatDir(w.root);
+    if (p === '/api/doccat/correct') {
+      const out = body.clear === true
+        ? docCatCorrections.clear(dir, rel)
+        : docCatCorrections.set(dir, rel, { category: body.category, ticket_kind: body.ticket_kind === undefined ? null : body.ticket_kind });
+      if (!out.ok) return json(res, { ok: false, error: out.error }, /could not be saved|symlink/.test(out.error) ? 500 : 400);
+      return json(res, { ok: true, ws: w.id, path: rel, cleared: body.clear === true ? out.cleared : undefined, correction: out.correction || null, corrections: docCatCorrections.get(dir) });
+    }
+    // the write-back
+    if (lst.isSymbolicLink() || !lst.isFile()) return json(res, { ok: false, error: 'This document is a link or not a plain file, so the category was not written into it.' }, 400);
+    let current;
+    try { current = fs.readFileSync(full, 'utf8'); }
+    catch { return json(res, { ok: false, error: 'could not read the document' }, 404); }
+    const corr = { category: body.category, ticket_kind: body.ticket_kind === undefined ? null : body.ticket_kind };
+    if (body.confirm !== true) {
+      const plan = docCatWriteback.plan(current, corr);
+      if (!plan.ok) return json(res, { ok: false, error: plan.error, sha: plan.sha }, 400);
+      return json(res, { ok: true, ws: w.id, path: rel, written: false, diff: plan.diff, changes: plan.changes, sha: plan.sha, next_sha: plan.next_sha, unchanged: plan.unchanged });
+    }
+    const done = docCatWriteback.apply(current, corr, body.expect_sha, body.expect_next_sha);
+    if (!done.ok) return json(res, { ok: false, error: done.error, stale: !!done.stale, sha: done.sha }, done.stale ? 409 : 400);
+    if (done.unchanged) return json(res, { ok: true, ws: w.id, path: rel, written: false, unchanged: true, diff: '' });
+    try { fs.writeFileSync(full, done.next); }
+    catch (e) {
+      warnWriteFail('category write-back (' + rel + ')', e);
+      return json(res, { ok: false, error: 'could not write the document — nothing was changed' }, 500);
+    }
+    return json(res, { ok: true, ws: w.id, path: rel, written: true, diff: done.diff, changes: done.changes, sha: docCatWriteback.sha1(done.next) });
+  }
   // ── D80 — Jev on changed claim pairs: the switch, a resume after a pause, and the backlog (plan, then confirmed run) ──
   if (p === '/api/claims/jev' && req.method === 'POST') {
     let body = {};
@@ -6243,6 +6474,18 @@ async function handleRequest(req, res) {
     if (!out.ok) return json(res, { ok: false, error: out.error }, 500);
     return json(res, { ok: true, ws: w.id, jev: jevGateInfo(w) });
   }
+  // D83 — the second switch: also read the documents tied to each initiative for the two status questions. Default off.
+  if (p === '/api/claims/jev/status' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    if (typeof body.status_read !== 'boolean') return json(res, { ok: false, error: 'status_read must be true or false' }, 400);
+    const out = tsSettings.setRepo(STATE, w.root, { status_read: body.status_read });
+    if (!out.ok) return json(res, { ok: false, error: out.error }, 500);
+    return json(res, { ok: true, ws: w.id, jev: jevGateInfo(w) });
+  }
   if (p === '/api/claims/jev/resume' && req.method === 'POST') {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }
@@ -6262,14 +6505,61 @@ async function handleRequest(req, res) {
     const g = jevClaims.gates({ key: tsSettings.status(STATE).present, consent: f.consent, watch: true, jev: f.jev });
     if (!g.open) return json(res, { ok: false, error: jevClaims.gateSentence(g.missing) }, 409);
     const { cacheDir, ledgerFile } = claimsPaths(w);
-    if (body.confirm !== true) return json(res, { ok: true, ws: w.id, plan: jevClaims.backlogPlan({ root: w.root, cacheDir, exclude: f.exclude }) });
+    if (body.confirm !== true) return json(res, { ok: true, ws: w.id, plan: jevClaims.backlogPlan({ root: w.root, cacheDir, exclude: f.exclude, model: jevRoute.modelFromPolicy(w.root) || undefined, flags: f }) });
     if (claimsRunning.has(w.root)) return json(res, { ok: false, busy: true, error: 'a check is already running for this repository' }, 409);
     claimsRunning.add(w.root);
     try {
-      const out = await jevClaims.runBacklog({ root: w.root, cacheDir, ledgerFile, key: tsSettings.getKey(STATE), flags: f, exclude: f.exclude, expectRequests: body.expect_requests });
+      const out = await jevClaims.runBacklog({ root: w.root, cacheDir, ledgerFile, key: tsSettings.getKey(STATE), flags: f, exclude: f.exclude, expectRequests: body.expect_requests, askOpts: jevModelOpts(w.root) });
       return json(res, { ws: w.id, ...out, jev: jevGateInfo(w), ...claimsLib.readView({ cacheDir, ledgerFile }) }, out.ok ? 200 : (out.conflict ? 409 : 500));
     } finally { claimsRunning.delete(w.root); }
   }
+  // ── D82 — Jev on documents the local rules leave undetermined: the switch, a resume, and the run (plan, then confirmed) ──
+  if (p === '/api/doccat/jev' && req.method === 'GET') {
+    const w = getWs(url.searchParams.get('ws'));
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    return json(res, { ok: true, ws: w.id, doccat: doccatInfo(w) });
+  }
+  if (p === '/api/doccat/jev' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    if (typeof body.categorize !== 'boolean') return json(res, { ok: false, error: 'categorize must be true or false' }, 400);
+    const out = tsSettings.setRepo(STATE, w.root, { categorize: body.categorize });
+    if (!out.ok) return json(res, { ok: false, error: out.error }, 500);
+    return json(res, { ok: true, ws: w.id, doccat: doccatInfo(w) });
+  }
+  if (p === '/api/doccat/jev/resume' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    jevCategorize.resume(doccatDir(w.root));
+    return json(res, { ok: true, ws: w.id, doccat: doccatInfo(w) });
+  }
+  if (p === '/api/doccat/jev/run' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = getWs(body.ws);
+    if (!w) return json(res, { ok: false, error: 'no workspace' }, 400);
+    const f = tsSettings.getRepo(STATE, w.root);
+    const g = jevCategorize.gates({ key: tsSettings.status(STATE).present, consent: f.consent, categorize: f.categorize });
+    if (!g.open) return json(res, { ok: false, error: jevCategorize.gateSentence(g.missing), doccat: doccatInfo(w) }, 409);
+    const cacheDir = doccatDir(w.root);
+    const docs = doccatDocs(w.root, library(w.root));
+    const named = namedRecords(w.root);
+    if (body.confirm !== true) return json(res, { ok: true, ws: w.id, plan: jevCategorize.plan({ docs, named, cacheDir, exclude: f.exclude }) });
+    if (doccatRunning.has(w.root)) return json(res, { ok: false, busy: true, error: 'Jev is already categorizing this repository' }, 409);
+    doccatRunning.add(w.root);
+    try {
+      const out = await jevCategorize.runConfirmed({ docs, named, cacheDir, key: tsSettings.getKey(STATE), flags: f, exclude: f.exclude, expectRequests: body.expect_requests,
+        expectFingerprint: typeof body.expect_fingerprint === 'string' ? body.expect_fingerprint : null });
+      return json(res, { ws: w.id, ...out, doccat: doccatInfo(w) }, out.ok ? 200 : (out.conflict || out.busy ? 409 : 500));
+    } finally { doccatRunning.delete(w.root); }
+  }
   // ── D79 — repository validation through TypeSafe ──────────────────────────────────────────────────
   // The ONLY routes that lead to an outbound request, and only through lib/typesafe.js. The key is never
   // in a response: `status` says present or absent. Nothing here edits a repository file.
@@ -6300,6 +6590,58 @@ async function handleRequest(req, res) {
     }
     return json(res, { ok: true, ws: w.id, name: w.name, ...tsSettings.getRepo(STATE, w.root), key: tsSettings.status(STATE) });
   }
+  /* ── live notes (jev-live-notes, Run 2): the ranked proposals of a conversation, and the PM's accept, change or reject.
+   *    Reads the repository's ledger; the writes are ledger rows and, on close, the day's note. No request leaves this process.
+   *    The page is the cockpit's live-notes view (public/pm/view-livenotes.js, Run 6). ── */
+  if (p === '/api/live-notes' && req.method === 'GET') {
+    const wsq = url.searchParams.get('ws');
+    const w = wsq ? workspaces.get(wsq) : homeWorkspace();     // a named workspace the server does not know is refused, never replaced by the home one
+    if (!w) return json(res, { ok: false, error: 'no such workspace' }, 400);
+    const r = liveNotes.apiList({ root: w.root, session: url.searchParams.get('session') || null, exclude: tsSettings.getRepo(STATE, w.root).exclude });
+    if (r.ok) r.jev = liveJevInfo(w);
+    return json(res, r, r.ok ? 200 : (r.status || 400));
+  }
+  if (p === '/api/live-notes/decide' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = body.ws ? workspaces.get(String(body.ws)) : homeWorkspace();
+    if (!w) return json(res, { ok: false, error: 'no such workspace' }, 400);
+    const r = liveNotes.apiDecide({ root: w.root, runtimeDir: STATE, session: body.session, segment: body.segment, action: body.action, initiative: body.initiative || null, relation: body.relation || null, question: body.question == null ? null : body.question, exclude: tsSettings.getRepo(STATE, w.root).exclude });
+    return json(res, r, r.ok ? 200 : (r.status || 400));
+  }
+  /* Run 7 (D85): the per-repository switch "live notes may use Jev". Default off; it is one of three gates, with the key and consent. */
+  if (p === '/api/live-notes/switch' && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = body.ws ? workspaces.get(String(body.ws)) : homeWorkspace();
+    if (!w) return json(res, { ok: false, error: 'no such workspace' }, 400);
+    if (typeof body.live !== 'boolean') return json(res, { ok: false, error: 'say live: true or live: false' }, 400);
+    liveNotes.setSwitch(STATE, w.root, { live: body.live });
+    return json(res, { ok: true, ws: w.id, jev: liveJevInfo(w) });
+  }
+  /* Run 6: the live-notes view's writes — start or resume a session, add points, close. A proposal is a local word match made in
+   * this process, unless all three D85 gates hold: then `add` hands each cleaned point to Jev through lib/jev-live.js. */
+  if ((p === '/api/live-notes/session' || p === '/api/live-notes/add' || p === '/api/live-notes/close' || p === '/api/live-notes/private') && req.method === 'POST') {
+    let body = {};
+    try { body = JSON.parse((await readBody(req)) || '{}'); }
+    catch { return json(res, { ok: false, error: 'invalid JSON body' }, 400); }
+    const w = body.ws ? workspaces.get(String(body.ws)) : homeWorkspace();
+    if (!w) return json(res, { ok: false, error: 'no such workspace' }, 400);
+    const exclude = tsSettings.getRepo(STATE, w.root).exclude;
+    let r;
+    if (p === '/api/live-notes/session') r = liveNotes.apiOpen({ root: w.root, runtimeDir: STATE, session: body.session || null, anchor: body.anchor || null, exclude });
+    else if (p === '/api/live-notes/add') {
+      const snd = liveSender(w);
+      r = await liveNotes.apiAdd({ root: w.root, runtimeDir: STATE, session: body.session, text: body.text, source: body.source === 'speech' ? 'speech' : 'typed', exclude,
+        key: snd.key, flags: snd.flags, ask: snd.ask, askOpts: snd.askOpts });
+    }
+    else if (p === '/api/live-notes/private') r = liveNotes.apiMarkPrivate({ root: w.root, session: body.session });
+    else r = liveNotes.apiClose({ root: w.root, runtimeDir: STATE, session: body.session, retentionDays: liveNotes.getSwitch(STATE, w.root).retention_days, exclude });
+    if (r.ok && p !== '/api/live-notes/close') { r.jev = liveJevInfo(w); if (r.note) r.note = r.jev.note; }
+    return json(res, r, r.ok ? 200 : (r.status || 400));
+  }
   if (p === '/api/validate/plan' && req.method === 'POST') {
     let body = {};
     try { body = JSON.parse((await readBody(req)) || '{}'); }

package/workspace/skills/live-notes.skill

@@ -0,0 +1,58 @@
+---
+name: live-notes
+label: "Live notes"
+description: "Take the talking points of a conversation, place each against the open initiatives, add a short cited context note where one is needed, and propose titles for new-initiative candidates. Proposals only; nothing is created, changed or decided."
+run: agent
+agent: claude
+tier: balanced
+version: 1.1.0
+owner: wawan
+risk: low
+scope: read:connectors, read:state, write:state/live-notes
+output:
+  - Placed talking points
+  - Context notes
+  - Candidates for new initiatives
+  - Sources reached and not reached
+---
+
+/live-notes — place a conversation against this repository's initiatives (jev-live-notes). Work only from the text you are given or can read with the connectors you already have. Do not guess.
+
+Rules that always hold:
+1. PROPOSALS ONLY. Never create, edit, accept, close or hold an initiative. Never write a decision, an acceptance or a run row. A candidate for a new initiative becomes one only when the PM presses through pmos-router.
+2. READ-ONLY on every source. Never send, reply, post, comment, create, edit, label or delete anything in a connected source.
+3. NOTHING LEAVES THIS MACHINE UNLESS THE COMMAND SAYS SO. Send a talking point to Typesafe only when the command's `path` line says `jev-agent`, and then only the point's words and the option list, never a speaker's name, a file or a key. On any other path, send nothing to any outside service. Report the path as the command says it.
+4. NOTHING INVENTED. A source you cannot reach is reported as not reached. A note you cannot support from the repository's own text says the text did not settle the point.
+5. PRIVATE STAYS PRIVATE. Skip anything marked private, personal, confidential or HR. The command withholds secret-shaped text; never paste it back.
+6. SHORT. A context note is at most 600 characters and cites the repository's own words exactly.
+
+Procedure (each step ends with a check that shows it is done):
+1. Find the segments. Segments are one per line in a file: plain text, or a JSON object with "text", "speaker", "source". If the PM gave you a file, use it. Otherwise use the source step below, or ask the PM for the text.
+   Done when: you can name the segments file, or you have said no text was available.
+   Source step, Wispr Flow meetings (use it only when the PM asked for a meeting, or for what was said since the last time): run `pmos proactive settings` and read the `wispr` line under "brief sources". If it is off, say "wispr: off" and stop; do not read it. If it is on:
+   a. List meetings with the Wispr Flow `search_meetings` tool, `since` the time of the last meeting you ingested (keep that cursor in your own notes for this session; with none, ask the PM which meeting). Use only the meeting's title, time, id, share link and whether it has a transcript.
+   b. Skip any meeting whose title or folder says private, personal, confidential or HR. Count the skipped ones and say the count; do not read them.
+   c. For each other meeting that has a transcript, read it with `get_meeting` and `view_transcript`, one bounded range at a time, using the continuation offset until it ends. Write the transcript text to a file in the scratch folder. Never copy the meeting's notes or summary anywhere.
+   d. Run `node workspace/bin/live-notes.js ingest --repo . --transcript <that file> --source "wispr:<meeting id>" --session <id>`. It adds only what is new, so reading a growing transcript again is safe. The pointer on each point names the meeting; give the PM the share link in your final message.
+   e. If the connector is not available in this session, or a call fails, say "wispr: not reached" with the reason. Do not make up a transcript.
+   Done when: each meeting you tried is read, skipped (counted) or not reached, and ingest printed its session and any duplicates skipped.
+2. Run `node workspace/bin/live-notes.js run --repo . --segments <file> --session <id>`. Give `--anchor domain:<id>` when it says too many initiatives match. It prints the path it ran, any withheld lines, and a prompt.
+   Done when: the command printed a session id and either rows or a prompt.
+3. Answer the prompt it printed, in its exact shape: one `LIVENOTE {json}` line per talking point, to a file in the scratch folder. Use "answers" only when the point answers a named open question, and name it. If the prompt says to use the Typesafe skill, use it for the initiative and relation choices and write "by":"jev"; if the skill or the key is missing, or a call fails, decide yourself and write "by":"agent". Never write "by":"jev" for a choice you made yourself. Then run `node workspace/bin/live-notes.js run --repo . --session <id> --answers <that file>`.
+   Done when: every talking point has a proposed row, or the command named why one was refused.
+4. Run `node workspace/bin/live-notes.js plan --repo . --session <id>`. For each context note it lists, read the files it names, then write one `LIVECONTEXT {json}` line: `{"segment":"<id>","note":"<at most 600 characters>","settled":true,"cites":[{"path":"<repository path>","quote":"<an exact passage of that file, at least 8 characters>"}]}`. Set "settled" to false when the initiative's own text does not decide the point. Use the tier the plan names for each step: ask `pmos-model recommend "<the work>" --skill live-notes` if you can launch a sub-task on a model.
+   For each candidate it lists, write one `LIVECANDIDATE {json}` line: `{"candidate":"<id>","title":"<at most 80 characters>","lane":"feature|discovery|chore|incident|content|prototype"}`. Run the pmos-router sharpness and prior-rejection questions in your head first; the command records the prior-rejection check on the title.
+   Put all the lines in one file and run `node workspace/bin/live-notes.js context --repo . --session <id> --answers <that file>`. Read any rejection, fix the line and run it once more. Do not work around a refusal.
+   Done when: the command says how many notes and drafts it accepted and nothing is left rejected.
+5. Show the PM the list and wait. The PM's accept, change and reject go in through `node workspace/bin/live-notes.js decide`, one per point, only when the PM says so. Do not decide for them.
+   Done when: you have shown the list and recorded nothing the PM did not say.
+6. When the PM says the conversation is over, run `node workspace/bin/live-notes.js close --repo . --session <id>`. It appends a section to today's requirements note and deletes the raw transcript.
+   Done when: the command printed the note path and "transcript: deleted", or the retention date the PM set.
+7. Finish by saying in two lines how many points were placed, how many are still unanswered, which path ran, and which sources were not reached. Do not commit; the PM's Sync carries the files.
+   Done when: the two lines are said once and no commit was made.
+
+Output contract — produce EXACTLY these sections in your final message:
+- Placed talking points
+- Context notes
+- Candidates for new initiatives
+- Sources reached and not reached