create-pmos 0.133.0 → 0.135.0

package/workspace/lib/engine/trust/plan.js

@@ -0,0 +1,5 @@
+// Ported verbatim from the PM's sample (prototype/pmos-console-handoff/sample/plan.js on feat/console3-merge); source of truth for this control. Only the fixture path (PF) and this header differ.
+const D=86400000,day=s=>Date.parse(s+'T00:00:00Z'),fmt=ms=>new Date(ms).toISOString().slice(0,10);
+const fold=(events,cut)=>{const s={};for(const e of events){if(cut&&e.snap>cut)continue;if(e.kind==='add')s[e.ticket]={...e.fields,origin:e.by,edits:0};else if(e.kind==='status'&&s[e.ticket]){s[e.ticket].status=e.fields.status}else if(s[e.ticket]){Object.assign(s[e.ticket],e.fields);s[e.ticket].edits++}}return s};
+const plan=(s,start)=>{const end={};const go=(k,seen=[])=>{if(seen.includes(k))throw new Error('dependency cycle at '+k);return end[k]??(end[k]=Math.max(day(start),...(s[k].deps||[]).map(d=>{if(!s[d])throw new Error(k+' depends on unknown '+d);return go(d,[...seen,k])}))+s[k].dur*D)};Object.keys(s).forEach(k=>go(k));return{end,forecast:Math.max(...Object.values(end))}};
+module.exports={fold,plan,day,fmt,D};

package/workspace/lib/engine/trust/trust.js

@@ -0,0 +1,21 @@
+// Ported verbatim from the PM's sample (prototype/pmos-console-handoff/sample/trust.js on feat/console3-merge); source of truth for this control. Only the fixture path (PF) and this header differ.
+// Claim checker: every claim carries one label and what that label requires. Strictness depends on the destination.
+module.exports.checkReport=function(rep,rules,ctx,dest){
+ const R=rules.destinations[dest],rows=[];
+ for(const c of rep.sections){let v='ok',why='';const set=(lvl,msg)=>{if(v==='block')return;if(lvl==='block'||v==='ok'){v=lvl;why=msg}};
+  const def=rules.basis[c.basis];
+  if(!c.basis||!def)set(R.unlabelled,'no label (fact, cited, reported, estimate, assumption or judgement)');
+  else if(!R.allow.includes(c.basis))set('block',c.basis+' is not allowed for '+dest);
+  else if((c.source||'').startsWith('import:')&&c.basis!=='reported')set('block','source is an untrusted import; the claim must be labelled reported');
+  else{const miss=def.needs.filter(k=>!c[k]);if(miss.length)set(R.incomplete,'missing '+miss.join(', '));
+   if(c.basis==='fact'||c.basis==='cited'){const m=(c.source||'').split('@');
+    if(m[0]==='forecast'||m[0]==='points'){if(!ctx.snaps.includes(m[1]))set('block','no such check '+m[1]);else if(m[1]<ctx.last)set(R.stale,'source is the '+m[1]+' check; latest is '+ctx.last)}
+    else if(!ctx.docs[m[0]])set('block','source '+m[0]+' does not exist');
+    else if(m[1]&&+m[1]<ctx.docs[m[0]].rev)set(R.stale,m[0]+' is now rev '+ctx.docs[m[0]].rev+'; claim used rev '+m[1])}
+   if(c.basis==='assumption'&&c.review_by&&c.review_by<ctx.now)set(R.overdue_assumption,'review date '+c.review_by+' has passed')}
+  rows.push({id:c.id,basis:c.basis||'(none)',claim:c.claim,verdict:v,why})}
+ // bad news rule: every tripped signal must be covered by a section
+ const covered=new Set(rep.sections.flatMap(s=>s.covers||[]));const omitted=(ctx.tripped||[]).filter(x=>!covered.has(x));
+ if(omitted.length&&R.unlabelled==='block')rows.push({id:'omitted',basis:'(rule)',claim:'Report omits tripped signal: '+omitted.join(', '),verdict:'block',why:'a report must cover every tripped signal'});
+ const blocked=rows.filter(r=>r.verdict==='block').length;
+ return{rows,send:blocked===0?'allowed':'blocked ('+blocked+' claim'+(blocked>1?'s':'')+')',label_visible:R.label_visible}};

package/workspace/lib/engine/truth-table.js

@@ -0,0 +1,57 @@
+'use strict';
+// console3 wave B4: the who-holds-what truth table. Pure. No I/O, no send.
+// messages: [{ id?, to, at, claims: [{ id, text?, value? }] }]   (what each person was told)
+// truth:    { [claimId]: { value, text?, changed_at? } }          (what is true now)
+// Only claims present in messages are listed. A claim is never invented.
+// State per told claim (the person's latest message on that claim):
+//   contradicted  the truth has a value and it differs from the value told
+//   stale         the truth changed after the message, or the truth for the claim is not known
+//   in sync       the truth holds the value told and has not changed since
+const V = require('./derived/derive.js');
+// BACKED BY THE PM'S SAMPLE: whoHoldsWhatFromPlan below is reader.js section 7 (derive.heldVsTrue): the truth is DERIVED from the
+// plan, 'ship-date' = the forecast and 'ticket:<id>' = that ticket's end, and a claim is in sync or N days apart.
+// REPO-WRITTEN, no sample equivalent: whoHoldsWhat, the generic claim table with the 'stale' state (truth changed after the send).
+const same = (a, b) => JSON.stringify(a === undefined ? null : a) === JSON.stringify(b === undefined ? null : b);
+const ts = (v) => { const t = Date.parse(v); return Number.isNaN(t) ? null : t; };
+
+function stateOf(told, at, now) {
+  if (!now || typeof now !== 'object') return 'stale';
+  if ('value' in now && told.value !== undefined && !same(told.value, now.value)) return 'contradicted';
+  if (told.value === undefined && 'text' in now && told.text !== undefined && told.text !== now.text) return 'contradicted';
+  const changed = ts(now.changed_at), sent = ts(at);
+  if (changed !== null && (sent === null || changed > sent)) return 'stale';
+  return 'in sync';
+}
+
+const RANK = { 'in sync': 0, stale: 1, contradicted: 2 };
+
+function whoHoldsWhat(messages = [], truth = {}) {
+  const people = new Map();
+  const list = (Array.isArray(messages) ? messages : []).slice().sort((a, b) => (ts(a && a.at) || 0) - (ts(b && b.at) || 0));
+  for (const m of list) {
+    if (!m || !m.to || !Array.isArray(m.claims)) continue;
+    if (!people.has(m.to)) people.set(m.to, new Map());
+    for (const c of m.claims) {
+      if (!c || !c.id) continue;
+      people.get(m.to).set(c.id, { ...c, at: m.at || null }); // the later message replaces the earlier one
+    }
+  }
+  const t = truth && typeof truth === 'object' ? truth : {};
+  return [...people.entries()].map(([person, held]) => {
+    const claims = [...held.values()].map((c) => {
+      const now = Object.prototype.hasOwnProperty.call(t, c.id) ? t[c.id] : null;
+      return {
+        id: c.id, text: c.text || null, told_at: c.at, told_value: c.value === undefined ? null : c.value,
+        truth_value: now && 'value' in now ? now.value : null, state: stateOf(c, c.at, now),
+      };
+    });
+    const worst = claims.reduce((w, c) => (RANK[c.state] > RANK[w] ? c.state : w), 'in sync');
+    return { person, claims, state: worst };
+  });
+}
+
+// messages: sent.jsonl records { to, claims: [{ subject, value }] }; pl: derived/plan.js plan(state, start).
+// Returns one row per told claim: { to, subject, told, true, gap, state } with state 'in sync' | '<n>d apart' | 'unknown'.
+const whoHoldsWhatFromPlan = (messages, pl) => V.heldVsTrue(Array.isArray(messages) ? messages : [], pl);
+
+module.exports = { whoHoldsWhatFromPlan, whoHoldsWhat, STATES: Object.keys(RANK) };

package/workspace/lib/engine/workspace-lib.js

@@ -0,0 +1,24 @@
+'use strict';
+/* workspace-lib.js — where a workspace/lib/ module is, for a script that runs in a checkout AND as a copy in a workspace
+ * package (incident workspace-package-script-closure).
+ *
+ *   require(workspaceLib('plan-items.js'))
+ *
+ * Some scripts share a fold with the workspace (the plan items, the item steps). In a checkout that module is at
+ * workspace/lib/<name>. In a package the script is a copy that scripts/vendor-workspace-engine.js put in lib/engine/,
+ * and this file is lib/engine/workspace-lib.js, so the module is the bundle's own lib/<name>, one folder up. A plain relative
+ * require of ../workspace/lib/x.js resolves in the first place only, and the vendor step refuses it.
+ *
+ * Both places are tried, the checkout first. When neither exists the checkout path is returned, and require() names it.
+ */
+const fs = require('fs');
+const path = require('path');
+
+function workspaceLib(name) {
+  const n = String(name || '');
+  if (!/^[a-z0-9][a-z0-9-]*\.js$/.test(n)) throw new Error(`workspaceLib: '${n}' must be a file name in workspace/lib/, such as 'plan-items.js'`);
+  const candidates = [path.join(__dirname, '..', 'workspace', 'lib', n), path.join(__dirname, '..', n)];
+  return candidates.find((p) => fs.existsSync(p)) || candidates[0];
+}
+
+module.exports = { workspaceLib };

package/workspace/lib/factory-join.js

@@ -53,7 +53,7 @@
 const fs = require('fs');
 const path = require('path');
 
-const WORK_ITEM_PATHS = [path.join(__dirname, '..', '..', 'scripts', 'work-item.js')];
+const WORK_ITEM_PATHS = [path.join(__dirname, '..', '..', 'scripts', 'work-item.js')];   // vendor: checkout-only — its sink guard is workspace/lib/sink.js, outside scripts/; an install reports engine-missing (header)
 const READY = new Set(['verified', 'integrated']);
 const PR_RE = /^(?:https?:\/\/\S+\/pull\/\d+\S*|pr:#?\d+)$/i;
 

package/workspace/lib/facts-async.js

@@ -24,8 +24,9 @@ const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const repoWatch = require('./repo-watch.js');
+const { repoScript } = require('./repo-script.js');
 
-const CLI = path.resolve(__dirname, '..', '..', 'scripts', 'signals', 'facts-cli.js');
+const CLI = repoScript('signals/facts-cli.js');   // a checkout's scripts/, or the copy vendored into lib/engine/
 const TTL_MS = 5 * 60 * 1000;            // only for a folder with no signature
 const MAX_AGE_MS = 24 * 3600 * 1000;     // an entry this old is rebuilt even when the signature holds
 const SIG_REUSE_MS = 2000;               // a burst of requests asks git once
@@ -41,8 +42,7 @@ const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
 /** The version of the code that derives the facts: a change to it makes every entry stale. */
 function engineVersion() {
   if (engineMemo) return engineMemo;
-  const sig = path.resolve(__dirname, '..', '..', 'scripts');
-  const parts = [CLI, path.join(sig, 'signals', 'facts.js'), path.join(sig, 'workflow-state.js')].map((f) => {
+  const parts = [CLI, repoScript('signals/facts.js'), repoScript('workflow-state.js')].map((f) => {
     try { return sha1(fs.readFileSync(f)); } catch { return '-'; }
   });
   engineMemo = sha1(parts.join('|')).slice(0, 12);
@@ -86,7 +86,7 @@ async function currentSig(root, opts, clock) {
 }
 
 function normalize(facts, today) {
-  try { return require('../../scripts/signals/facts.js').normalizeFacts(facts, today || undefined); } catch { return facts; }
+  try { return require(repoScript('signals/facts.js')).normalizeFacts(facts, today || undefined); } catch { return facts; }
 }
 
 function readFactsAsync(root, opts = {}) {

package/workspace/lib/headless.js

@@ -0,0 +1,95 @@
+'use strict';
+/* headless.js — which agent jobs run as headless Claude Code (`claude -p`) instead of a terminal pane
+ * (initiative workspace-headless-jobs; PM decision 2026-10-11: keep Jev, no direct Claude API, background
+ * jobs that need no human run headless).
+ *
+ *   kindFor({ agent, origin, skill, env })        → 'notes' | 'skill' | null   (null: open a pane, as before)
+ *   argsFor(kind, { modelArgs, addDirs })          → the argv after `claude`
+ *   parseResult(stdout)                            → { ok, text, isError, turns, durationMs, costUsd, denied[] }
+ *   logLines(result, exitCode)                     → the lines the read-only log pane shows at the end
+ *
+ * Pure: no I/O, no process. server.js spawnSession starts the child and keeps the session row.
+ *
+ * A headless run uses the PM's own login, model choice (D75), profile and connectors, exactly as a pane does.
+ * It cannot ask for permission, so each kind gets a FIXED tool list here; a connector tool runs only where the
+ * PM's own Claude Code settings already allow it, and anything else is denied and reported. No bypass flag is
+ * ever passed. `PMOS_HEADLESS=off` sends every job back to a pane.
+ */
+
+// The skills whose every start runs headless: they read, file a result for PMOS, and send nothing out.
+const HEADLESS_SKILLS = Object.freeze([
+  'day-check', 'calendar-sync', 'jira-sync', 'my-work-read', 'report-biweekly', 'report-template',
+  'tracker-refresh', 'measure', 'memory-groom', 'backlog-triage',
+]);
+// The note passes that run headless, by the origin prefix lib/routes-notes.js gives them.
+const HEADLESS_ORIGINS = Object.freeze(['notes-bullets:', 'notes-summary:']);
+
+// What each kind may use. Read-only search is always allowed. The notes passes write their JSON (and rename the .tmp
+// file) in their notes folder, which --add-dir opens to them; the skills also run `pmos` verbs and repository scripts.
+const TOOLS = Object.freeze({
+  notes: Object.freeze(['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash(mv *)']),
+  skill: Object.freeze(['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash(pmos *)', 'Bash(node *)',
+    'Bash(git log *)', 'Bash(git status *)', 'Bash(git diff *)', 'Bash(ls *)', 'Bash(date *)']),
+});
+
+const DEFAULT_TIMEOUT_MS = 20 * 60 * 1000;
+
+function switchedOff(env) {
+  return /^(off|0|false|no)$/i.test(String((env || process.env).PMOS_HEADLESS || '').trim());
+}
+
+function kindFor({ agent, origin, skill, env } = {}) {
+  if (agent !== 'claude' || switchedOff(env)) return null;
+  const o = String(origin || '');
+  if (HEADLESS_ORIGINS.some((p) => o.startsWith(p))) return 'notes';
+  if (skill && HEADLESS_SKILLS.includes(String(skill))) return 'skill';
+  return null;
+}
+
+function argsFor(kind, { modelArgs = [], addDirs = [] } = {}) {
+  const tools = TOOLS[kind];
+  if (!tools) throw new Error('unknown headless kind: ' + kind);
+  const argv = ['-p', '--output-format', 'json', '--no-session-persistence', ...modelArgs, '--allowedTools', tools.join(',')];
+  for (const d of addDirs) if (d) argv.push('--add-dir', String(d));
+  return argv;
+}
+
+function timeoutMs(env) {
+  const n = Number((env || process.env).PMOS_HEADLESS_TIMEOUT_MS);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_TIMEOUT_MS;
+}
+
+/** The last JSON object on stdout (`--output-format json` prints one). Anything unreadable is not a result. */
+function parseResult(stdout) {
+  const text = String(stdout || '').trim();
+  let o = null;
+  try { o = JSON.parse(text); } catch {
+    const at = text.lastIndexOf('\n{');
+    try { o = JSON.parse(at >= 0 ? text.slice(at + 1) : ''); } catch { o = null; }
+  }
+  if (!o || typeof o !== 'object') return { ok: false, text: text.slice(-2000), isError: true, turns: null, durationMs: null, costUsd: null, denied: [] };
+  const denied = Array.isArray(o.permission_denials)
+    ? [...new Set(o.permission_denials.map((d) => d && d.tool_name).filter(Boolean).map(String))] : [];
+  return {
+    ok: true,
+    text: typeof o.result === 'string' ? o.result : '',
+    isError: !!o.is_error || (typeof o.subtype === 'string' && o.subtype !== 'success'),
+    turns: Number.isFinite(o.num_turns) ? o.num_turns : null,
+    durationMs: Number.isFinite(o.duration_ms) ? o.duration_ms : null,
+    costUsd: Number.isFinite(o.total_cost_usd) ? o.total_cost_usd : null,
+    denied,
+  };
+}
+
+function logLines(r, exitCode) {
+  const out = [];
+  if (r.text) out.push(...String(r.text).split('\n'));
+  const facts = [`exit code ${exitCode}`];
+  if (r.durationMs != null) facts.push(`${Math.round(r.durationMs / 1000)} s`);
+  if (r.turns != null) facts.push(`${r.turns} turns`);
+  out.push('', `[${facts.join(' · ')}]`);
+  if (r.denied.length) out.push(`Not allowed in a background run: ${r.denied.join(', ')}. Allow these in Claude Code settings, or set PMOS_HEADLESS=off to use a terminal pane.`);
+  return out;
+}
+
+module.exports = { HEADLESS_SKILLS, HEADLESS_ORIGINS, TOOLS, DEFAULT_TIMEOUT_MS, kindFor, argsFor, timeoutMs, parseResult, logLines, switchedOff };

package/workspace/lib/import-overlay.js

@@ -9,7 +9,8 @@ const path = require('path');
 /** Where scripts/onboarding/ is: the checkout's own, else the copy an installed package vendors under lib/vendor/
  * (scripts/vendor-workspace-engine.js vendorTree). Null when neither is there. */
 function onboardingDir() {
-  for (const d of [path.join(__dirname, '..', '..', 'scripts', 'onboarding'), path.join(__dirname, 'vendor', 'scripts', 'onboarding')]) {
+  const inCheckout = path.dirname(path.join(__dirname, '..', '..', 'scripts', 'onboarding', 'scan.js'));   // vendor: checkout-only (vendorTree copies the onboarding tree)
+  for (const d of [inCheckout, path.join(__dirname, 'vendor', 'scripts', 'onboarding')]) {
     if (fs.existsSync(path.join(d, 'scan.js'))) return d;
   }
   return null;

package/workspace/lib/jira-status.js

@@ -13,8 +13,10 @@
  *   readSnapshot(root, initiative)      → { fetchedAt, query, tickets: Map<key, reading> } | null
  *   which(root, key)                    → the initiative and ticket a key belongs to
  *
- * A READING is { key, summary, status, category: todo|doing|done, sprint: { name, state: active|future|closed } | null,
- * subtasks: { done, total }, fixVersion: [names], flagged, reason, url }. A ticket the search did not return keeps its last reading, marked
+ * A READING is { key, summary, status, category: todo|doing|done, sprint: { name, state: active|future|closed, id?, start?, end?,
+ * completed? } | null, subtasks: { done, total }, fixVersion: [names], points: number | null, resolved: YYYY-MM-DD | null,
+ * flagged, reason, url }. The sprint's dates, `points` and `resolved` feed the sprint burndown (lib/stage-tools.js); a
+ * reading saved before they were carried has none of them, and the burndown says it cannot be drawn. A ticket the search did not return keeps its last reading, marked
  * stale. Titles and statuses only: never a description, a comment or a person.
  *
  * BOUNDARY (J15). No network module, no child process. The only write is the snapshot file.
@@ -83,7 +85,30 @@ function sprintOne(v) {
   const name = clip(oneLine(v.name), 80);
   const state = String(v.state || '').toLowerCase();
   if (!name) return null;
-  return { name, state: SPRINT_STATES.includes(state) ? state : 'active' };
+  const out = { name, state: SPRINT_STATES.includes(state) ? state : 'active' };
+  if ((Number.isInteger(v.id) && v.id > 0) || (isStr(v.id) && /^\d{1,12}$/.test(v.id))) out.id = String(v.id);
+  for (const [k, from] of [['start', ['startDate', 'start']], ['end', ['endDate', 'end']], ['completed', ['completeDate', 'completed']]]) {
+    const d = dayOf(from.map((f) => v[f]).find((x) => x != null));
+    if (d) out[k] = d;
+  }
+  return out;
+}
+/** An ISO date or date-time → YYYY-MM-DD (the date as written, never shifted by a zone), else null. */
+function dayOf(v) {
+  if (!isStr(v)) return null;
+  const m = /^(\d{4}-\d{2}-\d{2})(?:$|[T ])/.exec(v.trim());
+  return m ? m[1] : null;
+}
+/** Story points: a non-negative number, from the flat `points` or a points field Jira names (the custom field id differs per
+ * site; these are the common ones). null when none is set: an unpointed ticket, which the burndown counts apart. */
+const POINT_FIELDS = ['points', 'story_points', 'storyPoints', 'Story Points', 'Story point estimate', 'customfield_10016', 'customfield_10026', 'customfield_10028', 'customfield_10002'];
+function pointsIn(o) {
+  for (const k of POINT_FIELDS) {
+    const v = o[k];
+    if (typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1000) return v;
+    if (isStr(v) && /^\d{1,4}(\.\d+)?$/.test(v.trim())) return Number(v);
+  }
+  return null;
 }
 /** The sprint that matters: the active one, else the next, else the last closed. null is the backlog. */
 function sprintOf(v) {
@@ -134,6 +159,7 @@ function normalizeIssue(x) {
     const status = nameOf(st) || 'Unknown';
     const flagged = flaggedIn(f) || /block|impediment|on hold/i.test(status);
     return { key, summary, status, category: categoryOf(status, st.statusCategory), sprint: sprintIn(f), subtasks: subtasksOf(f.subtasks), fixVersion: fixVersionsOf(f.fixVersions),
+      points: pointsIn(f), resolved: dayOf(f.resolutiondate || f.resolved),
       flagged, reason: flagged ? (flaggedIn(f) ? 'Flagged in Jira' : `Status: ${status}`) : null, url: urlOf(x, key) };
   }
   // The flat shape: what the skill tells the agent to write when it is unsure of the connector's shape.
@@ -142,6 +168,7 @@ function normalizeIssue(x) {
   const status = oneLine(x.status) || 'Unknown';
   const flagged = x.flagged === true || /block|impediment|on hold/i.test(status);
   return { key, summary, status, category: categoryOf(status, x.category), sprint: sprintOf(x.sprint), subtasks: subtasksOf(x.subtasks), fixVersion: fixVersionsOf(x.fixVersions != null ? x.fixVersions : x.fixVersion),
+    points: pointsIn(x), resolved: dayOf(x.resolved || x.resolutiondate),
     flagged, reason: flagged ? clip(oneLine(x.reason || x.flag_reason || (x.flagged === true ? 'Flagged in Jira' : `Status: ${status}`)), 160) : null,
     url: urlOf(x, key) };
 }

package/workspace/lib/notes-audio.js

@@ -18,6 +18,9 @@
  * place and with nothing added, so the final pass after Stop (lib/notes-final.js) can tell the PM's microphone from the
  * meeting. remove deletes all three.
  *
+ * A chunk from a page that names its place (`sample`, from lib/notes-capture.js) is written exactly there, so a chunk that arrives
+ * late, or after a restart, lands where it belongs (notes-recording-reliability).
+ *
  * WHAT IT NEVER DOES. It sends nothing and opens no network module. The routes (lib/routes-notes.js) write nothing for a
  * private note, delete the file when a note is made private or deleted, and write nothing when the PM switches keeping off.
  */
@@ -80,20 +83,23 @@ function softLimit(x) {
 /** Add one chunk at meeting time `t`. Samples already there (the other source) are added to, then limited by softLimit. With
  * `mixed: false` only the source's own file is written: the PM keeps no audio for replay, and the final pass deletes it when done.
  * The per-source files are never limited: they are what the transcription reads. */
-function write(runtimeDir, { id, source, pcm, pcm24 = null, t, mixed = true }) {
+function write(runtimeDir, { id, source, pcm, pcm24 = null, t, sample = null, mixed = true }) {
   if (!ID_RE.test(String(id || '')) || !pcm || !pcm.length || pcm.length % 2) return { ok: false, error: 'nothing to keep' };
   const f = fileOf(runtimeDir, id);
   const key = f + '|' + source;
-  let at = Math.max(0, Math.round((Number(t) || 0) * BYTES_PER_MS / 2) * 2);
+  // `sample` (notes-recording-reliability): the chunk's own place, from the capture's start and its offset, so it is written there
+  // and nowhere else, whenever it arrives. Without it the chunk is placed by its arrival time, as before.
+  const exact = Number.isInteger(sample) && sample >= 0;
+  let at = exact ? sample * 2 : Math.max(0, Math.round((Number(t) || 0) * BYTES_PER_MS / 2) * 2);
   const prev = next.get(key);
   // a source never overlaps itself: a chunk that would start before its source left off, or just after, goes straight after it
-  if (prev !== undefined && at <= prev + ON_TIME_MS * BYTES_PER_MS) at = prev;
+  if (!exact && prev !== undefined && at <= prev + ON_TIME_MS * BYTES_PER_MS) at = prev;
   if (at >= MAX_BYTES) return { ok: true, kept: false };
   const len = Math.min(pcm.length, MAX_BYTES - at);
   fs.mkdirSync(dirOf(runtimeDir), { recursive: true });
   // With 24 kHz audio the replay is the 24 kHz mix and no 16 kHz mix is written; the 16 kHz source files are written either way
   const hiOk = mixed && pcm24 && pcm24.length && pcm24.length % 2 === 0;
-  if (hiOk) writeHi(runtimeDir, id, source, pcm24, t);
+  if (hiOk) writeHi(runtimeDir, id, source, pcm24, t, exact ? Math.round(sample * HI_RATE / RATE) : null);
   if (mixed && !hiOk) {
     const fd = fs.openSync(f, fs.existsSync(f) ? 'r+' : 'w+', 0o600);
     try {
@@ -114,12 +120,13 @@ function write(runtimeDir, { id, source, pcm, pcm24 = null, t, mixed = true }) {
 }
 
 /** Add one chunk of 24 kHz audio to the note's 24 kHz mix at meeting time `t`, placed as write() places the 16 kHz audio. */
-function writeHi(runtimeDir, id, source, pcm24, t) {
+function writeHi(runtimeDir, id, source, pcm24, t, sample = null) {
   const f = hiFileOf(runtimeDir, id);
   const key = f + '|' + source;
-  let at = Math.max(0, Math.round((Number(t) || 0) * HI_BYTES_PER_MS / 2) * 2);
+  const exact = Number.isInteger(sample) && sample >= 0;
+  let at = exact ? sample * 2 : Math.max(0, Math.round((Number(t) || 0) * HI_BYTES_PER_MS / 2) * 2);
   const prev = next.get(key);
-  if (prev !== undefined && at <= prev + ON_TIME_MS * HI_BYTES_PER_MS) at = prev;
+  if (!exact && prev !== undefined && at <= prev + ON_TIME_MS * HI_BYTES_PER_MS) at = prev;
   if (at >= HI_MAX_BYTES) return;
   const len = Math.min(pcm24.length, HI_MAX_BYTES - at);
   const fd = fs.openSync(f, fs.existsSync(f) ? 'r+' : 'w+', 0o600);
@@ -155,12 +162,24 @@ function remove(runtimeDir, id) {
   for (const k of [...next.keys()]) if (k.startsWith(fileOf(runtimeDir, id) + '|') || k.startsWith(hiFileOf(runtimeDir, id) + '|')) next.delete(k);
   for (const src of SOURCES) { try { fs.unlinkSync(sourceFileOf(runtimeDir, id, src)); } catch { /* none */ } }
   let removed = false;
-  for (const extra of ['.echo.json', '.pcm.echo.tmp', '.hi.pcm.echo.tmp', '.hi.pcm', '.clean.pcm', '.clean.pcm.tmp']) {
+  for (const extra of ['.capture.json', '.echo.json', '.pcm.echo.tmp', '.hi.pcm.echo.tmp', '.hi.pcm', '.clean.pcm', '.clean.pcm.tmp']) {
     try { fs.unlinkSync(path.join(dirOf(runtimeDir), id + extra)); if (extra === '.hi.pcm') removed = true; } catch { /* none */ }
   }
   try { fs.unlinkSync(fileOf(runtimeDir, id)); removed = true; } catch { /* none */ }
   return removed;
 }
+/** Samples [from, to) (16 kHz) of one source's own file, or null. At most a minute. */
+function readSource(runtimeDir, id, source, from, to) {
+  if (!ID_RE.test(String(id || '')) || !SOURCES.includes(source)) return null;
+  const a = Math.max(0, from, to - RATE * 60); const n = (to - a) * 2;
+  if (n <= 0) return null;
+  let fd;
+  try {
+    fd = fs.openSync(sourceFileOf(runtimeDir, id, source), 'r');
+    const b = Buffer.alloc(n); const got = fs.readSync(fd, b, 0, n, a * 2);
+    return got > 0 ? { pcm: b.subarray(0, got - (got % 2)), from: a } : null;
+  } catch { return null; } finally { if (fd !== undefined) fs.closeSync(fd); }
+}
 /** The note's audio, one file per source: [{ source, file, bytes, ms }], the sources that were heard. */
 function sources(runtimeDir, id) {
   if (!ID_RE.test(String(id || ''))) return [];
@@ -220,4 +239,4 @@ function serve(req, res, runtimeDir, id) {
   fs.createReadStream(inf.file, { start: from, end: to }).on('error', () => res.end()).pipe(res);
 }
 
-module.exports = { write, info, remove, removeSources, sources, serve, getKeep, setKeep, getClean, setClean, hasClean, replayOf, wavHeader, softLimit, replayFile: (dir, id) => (baseOf(dir, id) || { file: fileOf(dir, id) }).file, mixFile: fileOf, hiFile: hiFileOf, sideFile: sideFileOf, baseOf, cleanFile: cleanFileOf, HI_RATE, RATE, BYTES_PER_MS, MAX_BYTES };
+module.exports = { write, readSource, info, remove, removeSources, sources, serve, getKeep, setKeep, getClean, setClean, hasClean, replayOf, wavHeader, softLimit, replayFile: (dir, id) => (baseOf(dir, id) || { file: fileOf(dir, id) }).file, mixFile: fileOf, hiFile: hiFileOf, sideFile: sideFileOf, baseOf, cleanFile: cleanFileOf, HI_RATE, RATE, BYTES_PER_MS, MAX_BYTES };

package/workspace/lib/notes-capture.js

@@ -0,0 +1,136 @@
+'use strict';
+/* notes-capture.js — which page is capturing a note, and which chunks of it are already written (notes-recording-reliability). Local only.
+ *
+ *   start(runtimeDir, id, { baseMs, now }) → { ok, token, base_ms } | { ok: false, status: 409, error }
+ *   check(runtimeDir, id, { token, source, seq, now }) → { ok, dup, base_ms } | { ok: false, status: 409, error }
+ *   mark(runtimeDir, id, { source, seq, now })   the chunk is written: a second copy of it is a duplicate
+ *   setCut(runtimeDir, id, { source, sample }) · untranscribed(runtimeDir, id, { source, before }) → { from, to } | null
+ *                                                the live transcription's progress, so a restart transcribes what it had buffered
+ *   close(runtimeDir, id)                        Pause or Stop: the capture ends, and the next Listen starts a new one
+ *   tokened(runtimeDir, id) → true when the live capture has sent a chunk with its token
+ *   owns(runtimeDir, id, { token }) → { ok, base_ms } | { ok: false, status: 409, error }   is this the live, not-closed capture's token
+ *                                                (a screenshot has no sequence number, so it is checked on the token alone)
+ *   remove(runtimeDir, id)
+ *
+ * WHY. The page sends each source in one-second chunks and sends a chunk again when its answer does not come back. Before this
+ * module, the server placed each chunk at its arrival time and remembered in memory where each source ended. So a chunk written
+ * twice was kept twice, a restart lost the memory and the next chunk was added onto audio already written, a late chunk moved
+ * the rest of its source, and two tabs could capture one note into the same file (measured by notes-duplication.test.js).
+ *
+ * WHAT IT KEEPS. Listen hands the page a token and the meeting time the capture starts at (base_ms). Each chunk carries the
+ * token, a sequence number per source and its sample offset in the capture, so the route places it at base_ms + offset, and
+ * the sequence numbers already written are kept as ranges. All of it is in `<runtime>/notes/recordings/<id>.capture.json`,
+ * next to the audio, so a restart keeps it.
+ *
+ * ONE CAPTURE PER NOTE. Listen is refused while another capture is live: one that sent a chunk (or started) in the last
+ * LIVE_MS. A chunk with a token that is not the note's capture is refused, and the page stops listening on that answer.
+ *
+ * WHAT IT NEVER DOES. It sends nothing and opens no network module.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const LIVE_MS = 5000;
+const ID_RE = /^n-[0-9a-z]{4,16}-[0-9a-f]{4}$/;
+const fileOf = (runtimeDir, id) => path.join(runtimeDir, 'notes', 'recordings', id + '.capture.json');
+const cache = new Map();   // file → state, written through to the file
+
+function load(runtimeDir, id) {
+  const f = fileOf(runtimeDir, id);
+  if (cache.has(f)) return cache.get(f);
+  let s = null;
+  try { s = JSON.parse(fs.readFileSync(f, 'utf8')); } catch { s = null; }
+  if (!s || typeof s !== 'object') s = null;
+  cache.set(f, s);
+  return s;
+}
+function save(runtimeDir, id, s) {
+  const f = fileOf(runtimeDir, id);
+  cache.set(f, s);
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  const tmp = f + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(s), { mode: 0o600 });
+  fs.renameSync(tmp, f);
+}
+const liveAt = (s) => Math.max(Date.parse(s.started_at) || 0, Date.parse(s.last_at) || 0);
+const isLive = (s, now) => !!(s && s.token && !s.closed && now - liveAt(s) < LIVE_MS);
+
+/** A new capture, unless another one is live. */
+function start(runtimeDir, id, { baseMs = 0, now = Date.now() } = {}) {
+  if (!ID_RE.test(String(id || ''))) return { ok: false, status: 400, error: 'no such note' };
+  const s = load(runtimeDir, id);
+  if (isLive(s, now)) return { ok: false, status: 409, error: 'this meeting is already being recorded in another tab or window' };
+  const token = crypto.randomBytes(9).toString('hex');
+  const base = Math.max(0, Math.round(Number(baseMs) || 0));
+  save(runtimeDir, id, { token, base_ms: base, started_at: new Date(now).toISOString(), last_at: null, closed: false, tokened: false, seqs: {} });
+  return { ok: true, token, base_ms: base };
+}
+/** Refuse true when another check would refuse the next Listen: used before the note's own record step changes anything. */
+function busy(runtimeDir, id, { now = Date.now() } = {}) { return isLive(load(runtimeDir, id), now); }
+
+const has = (ranges, n) => (ranges || []).some(([a, b]) => n >= a && n <= b);
+function add(ranges, n) {
+  const r = (ranges || []).concat([[n, n]]).sort((x, y) => x[0] - y[0]);
+  const out = [];
+  for (const [a, b] of r) { const last = out[out.length - 1]; if (last && a <= last[1] + 1) last[1] = Math.max(last[1], b); else out.push([a, b]); }
+  return out;
+}
+
+/** May this chunk be written? `dup` when its sequence number is already written. */
+function check(runtimeDir, id, { token, source, seq } = {}) {
+  const s = load(runtimeDir, id);
+  if (!s || !s.token || s.closed || s.token !== token) return { ok: false, status: 409, error: 'this meeting is being recorded in another tab or window, or listening stopped' };
+  const n = Number(seq);
+  if (!Number.isInteger(n) || n < 0) return { ok: false, status: 400, error: 'a chunk needs a sequence number' };
+  return { ok: true, dup: has((s.seqs || {})[source], n), base_ms: s.base_ms };
+}
+function mark(runtimeDir, id, { source, seq, end = null, now = Date.now() } = {}) {
+  const s = load(runtimeDir, id);
+  if (!s) return;
+  s.seqs = s.seqs || {};
+  s.seqs[source] = add(s.seqs[source], Number(seq));
+  if (Number.isInteger(end)) { s.fed = s.fed || {}; s.fed[source] = Math.max(s.fed[source] || 0, end); }
+  s.last_at = new Date(now).toISOString(); s.tokened = true;
+  save(runtimeDir, id, s);
+}
+/** The live transcription cut this source up to `sample` (16 kHz). */
+function setCut(runtimeDir, id, { token, source, sample } = {}) {
+  const s = load(runtimeDir, id);
+  if (!s || s.closed || (token && s.token !== token) || !Number.isInteger(sample)) return;
+  s.cut = s.cut || {};
+  if (sample <= (s.cut[source] || 0)) return;
+  s.cut[source] = sample;
+  save(runtimeDir, id, s);
+}
+/** After a restart the live transcription lost what it had buffered: the stretch [from, to) of a source that was written but not
+ * transcribed, ending where the incoming chunk starts. null when there is none. */
+function untranscribed(runtimeDir, id, { source, before } = {}) {
+  const s = load(runtimeDir, id);
+  if (!s || s.closed) return null;
+  const base = Math.round((s.base_ms || 0) * 16);
+  const from = Math.max(base, (s.cut || {})[source] || 0);
+  const to = Math.min(before, (s.fed || {})[source] || 0);
+  return to > from ? { from, to } : null;
+}
+/** Does this token belong to the note's live capture, one that was not closed by Pause or Stop? Changes nothing. */
+function owns(runtimeDir, id, { token } = {}) {
+  const s = load(runtimeDir, id);
+  if (!s || !s.token || s.closed || s.token !== token) return { ok: false, status: 409, error: 'this meeting is being recorded in another tab or window, or listening stopped' };
+  return { ok: true, base_ms: s.base_ms };
+}
+function tokened(runtimeDir, id, { now = Date.now() } = {}) { const s = load(runtimeDir, id); return isLive(s, now) && !!s.tokened; }
+function close(runtimeDir, id) {
+  const s = load(runtimeDir, id);
+  if (!s || s.closed) return;
+  s.closed = true;
+  save(runtimeDir, id, s);
+}
+function remove(runtimeDir, id) {
+  if (!ID_RE.test(String(id || ''))) return;
+  const f = fileOf(runtimeDir, id);
+  cache.delete(f);
+  try { fs.unlinkSync(f); } catch { /* none */ }
+}
+
+module.exports = { start, busy, check, mark, setCut, untranscribed, close, tokened, owns, remove, LIVE_MS };

package/workspace/lib/notes-final.js

@@ -6,6 +6,7 @@
  *   createFinal({ runtimeDir, onDone, onState, run?, detect?, qwen? }) → { queue(id, opts), cancel(id), state(id), idle() }
  *   parseWhisper(json) · parseParakeet(json) · splitAtPauses(pcm) · assignSpeakers(segs, diar) · dropEcho(mic, meeting)
  *   mergeSources(parts)
+ *   transcribeClip(runtimeDir, pcm, { prompt }) → { ok, engine, segments }   one stretch through the same engine (notes-live-settle)
  *
  * WHY. The live transcript is cut every few seconds so that lines appear while people talk. A cut that short gives Whisper
  * little context, so names come out wrong and sentences break in two, and nothing in it says who spoke. Meeting tools that
@@ -276,6 +277,40 @@ async function transcribeQwen(qwen, d, pcmFile, tmp, { lang, prompt, live = () =
   }
   return { ok: true, segments, engine: 'qwen', vad: true };
 }
+/** The best engine set up first; when it fails, the next one still can: Qwen3-ASR, Parakeet (English), Whisper. */
+async function bestTranscript({ run, qwen }, d, pcmFile, wav, tmp, { prompt = '', live = () => true } = {}) {
+  const order = [];
+  if (d.qwen) order.push('qwen');
+  if (d.parakeet && d.lang === 'en') order.push('parakeet');
+  if (d.whisper) order.push('whisper');
+  let r = { ok: false, error: 'no engine is set up for the final pass' };
+  for (const e of order) {
+    if (!live()) return r;
+    r = e === 'qwen' ? await transcribeQwen(qwen, d, pcmFile, tmp, { lang: d.lang, prompt, live })
+      : e === 'parakeet' ? await transcribeParakeet(run, d, wav, tmp) : await transcribeWhisper(run, d, wav, tmp, { lang: d.lang, prompt });
+    if (r.ok) break;
+  }
+  return r;
+}
+/**
+ * One stretch of audio (16 kHz mono 16-bit samples) through the final pass's engine, with no speakers and nothing stored
+ * (notes-live-settle: what a settle tier would cost). → { ok, engine, segments } | { ok: false, error }
+ */
+async function transcribeClip(runtimeDir, pcm, { prompt = '', run = runProgram, detect: det = () => detect(runtimeDir),
+  qwen = (args) => notesQwen.runQwen(notesQwen.workerFor(runtimeDir), args) } = {}) {
+  const d = det();
+  if (!d.ready) return { ok: false, error: 'no engine is set up for the final pass' };
+  const tmp = path.join(finalDir(runtimeDir), 'tmp-' + crypto.randomBytes(6).toString('hex'));
+  try {
+    fs.mkdirSync(tmp, { recursive: true, mode: 0o700 });
+    const pcmFile = path.join(tmp, 'clip.pcm'); const wav = path.join(tmp, 'clip.wav');
+    fs.writeFileSync(pcmFile, pcm, { mode: 0o600 });
+    writeWav(pcmFile, wav);
+    return await bestTranscript({ run, qwen }, d, pcmFile, wav, tmp, { prompt });
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* gone */ }
+  }
+}
 async function diarizeFile(run, d, wav) {
   const r = await run(d.diarize.python, [d.diarize.script, '--segmentation', d.diarize.seg, '--embedding', d.diarize.emb, '--wav', wav, '--threshold', DIARIZE_THRESHOLD]);
   let j = null;
@@ -319,18 +354,8 @@ function createFinal({ runtimeDir, onDone, onState = () => {}, run = runProgram,
         const wav = path.join(tmp, s.source + '.wav');
         writeWav(s.file, wav);
         set(id, { state: 'running', step: 'transcribing ' + (s.source === 'mic' ? 'your microphone' : 'the meeting') + ' again' });
-        // the best engine first; when it fails, the next one set up still can: Qwen3-ASR, Parakeet (English), Whisper
-        const order = [];
-        if (d.qwen) order.push('qwen');
-        if (d.parakeet && d.lang === 'en') order.push('parakeet');
-        if (d.whisper) order.push('whisper');
-        let r = { ok: false, error: 'no engine is set up for the final pass' };
-        for (const e of order) {
-          if (!live()) return;
-          r = e === 'qwen' ? await transcribeQwen(qwen, d, s.file, tmp, { lang: d.lang, prompt, live })
-            : e === 'parakeet' ? await transcribeParakeet(run, d, wav, tmp) : await transcribeWhisper(run, d, wav, tmp, { lang: d.lang, prompt });
-          if (r.ok) break;
-        }
+        const r = await bestTranscript({ run, qwen }, d, s.file, wav, tmp, { prompt, live });
+        if (!live()) return;
         if (!r.ok) { set(id, { state: 'failed', reason: r.error }); return; }
         engine = r.engine; vad = vad || r.vad;
         let part = { source: s.source, segments: r.segments, speakers: 1 };
@@ -369,5 +394,5 @@ function createFinal({ runtimeDir, onDone, onState = () => {}, run = runProgram,
   };
 }
 
-module.exports = { detect, setupCommand, createFinal, runProgram, parseWhisper, parseParakeet, splitAtPauses, assignSpeakers, dropEcho, mergeSources, finalDir,
+module.exports = { detect, setupCommand, createFinal, transcribeClip, runProgram, parseWhisper, parseParakeet, splitAtPauses, assignSpeakers, dropEcho, mergeSources, finalDir,
   PARAKEET_MODEL, VAD_FILE, DIARIZE_THRESHOLD };