session-orchestrator 5.10.0 → 5.12.0

package/scripts/lib/so-hud/collect.mjs

@@ -0,0 +1,130 @@
+import path from 'node:path';
+import { parseStateMd } from '../state-md/yaml-parser.mjs';
+
+export const EVENT_NAMES = new Set([
+  'orchestrator.quality_gate.passed', 'orchestrator.quality_gate.failed',
+  'orchestrator.vault.mirror_run_completed', 'orchestrator.vault.board_written',
+]);
+const text = v => typeof v === 'string' && v.length ? v : null;
+const number = v => typeof v === 'number' && Number.isFinite(v) ? v : null;
+const positive = v => Number.isSafeInteger(v) && v > 0 ? v : null;
+export const safeId = v => typeof v === 'string' && /^[a-zA-Z0-9_-]{1,200}$/.test(v);
+
+export function parseEvents(tail) {
+  return tail.split('\n').flatMap(line => {
+    try {
+      const e = JSON.parse(line);
+      return EVENT_NAMES.has(e.event ?? e.event_type) ? [e] : [];
+    } catch { return []; }
+  }).sort((a, b) => (Date.parse(a.timestamp) || 0) - (Date.parse(b.timestamp) || 0));
+}
+
+export function gateFromEvent(e) {
+  if (!e) return null;
+  const failed = (e.event ?? e.event_type).endsWith('.failed') || e.check_failed === true || e.timed_out === true || (number(e.exit_code) !== null && e.exit_code !== 0);
+  const reporting = ['baseline', 'incremental', 'per-file'].includes(e.variant);
+  const proven = e.exit_code === 0 && (reporting ? e.check_failed === false : ['full-gate', 'auto-fix-loop'].includes(e.variant));
+  return { variant: text(e.variant), passed: failed ? false : proven ? true : null,
+    check_failed: typeof e.check_failed === 'boolean' ? e.check_failed : null,
+    exit_code: number(e.exit_code), at: text(e.timestamp) };
+}
+
+/** Both scope sources must be readable; incomplete dispatch never proves disjointness. */
+export function scopePaths(aggregate, dispatch) {
+  if (!Array.isArray(aggregate) || !dispatch || !Array.isArray(dispatch.agents)) return null;
+  if ((dispatch.scopeSignals?.['marker-absent'] ?? 0) > 0 || (dispatch.scopeSignals?.unparseable ?? 0) > 0) return null;
+  const rows = [...aggregate, ...dispatch.agents];
+  if (rows.some(r => !r || !Array.isArray(r.files) || r.files.some(f => typeof f !== 'string'))) return null;
+  return [...new Set(rows.flatMap(r => r.files))];
+}
+
+/** All I/O and time are supplied. No writes, host discovery or defaults hidden in this fold. */
+export async function collectSnapshot(repoRoot, readers) {
+  const degraded = [];
+  const read = async (file, json = false) => {
+    try {
+      const raw = await readers.readText(path.join(repoRoot, file));
+      return { value: json ? JSON.parse(raw) : raw, absent: false };
+    } catch (e) {
+      if (e.code !== 'ENOENT') degraded.push(`${file}:unreadable`);
+      return { value: null, absent: e.code === 'ENOENT' };
+    }
+  };
+  const now = readers.now();
+  const [lockResult, waveRead, stateRead, agentStatus, discovery, eventsRead, config, greenRead] = await Promise.all([
+    readers.lock(repoRoot), read('.claude/wave-scope.json', true),
+    readers.statePath ? read(readers.statePath) : read('.claude/STATE.md'),
+    readers.agents(repoRoot), readers.discover(repoRoot), readers.events(repoRoot), readers.config(repoRoot), read('.orchestrator/runtime/last-green-sha.txt'),
+  ]);
+  degraded.push(...(discovery.degraded ?? []), ...(eventsRead.degraded ?? []), ...(config.degraded ?? []));
+  if (!['ok', 'absent'].includes(lockResult.status)) degraded.push(`lock:${lockResult.status}`);
+  const lock = lockResult.lock ?? null;
+  const sid = readers.sessionId ?? lock?.session_id ?? null;
+  const wave = waveRead.value && typeof waveRead.value === 'object' && !Array.isArray(waveRead.value) ? waveRead.value : null;
+  const foreignWave = wave?.session_id && sid && wave.session_id !== sid;
+  if (foreignWave) degraded.push('wave:foreign-session');
+  const ownWave = foreignWave || !positive(wave?.wave) ? null : wave;
+  if (!waveRead.absent && !ownWave && !foreignWave) degraded.push('wave:invalid-or-unreadable');
+  const waveNumber = positive(ownWave?.wave);
+  const fm = parseStateMd(stateRead.value)?.frontmatter ?? {};
+  const foreignState = fm['session-id'] && sid && fm['session-id'] !== sid;
+  if (foreignState) degraded.push('state:foreign-session');
+  const state = foreignState ? {} : fm;
+  const dispatch = safeId(sid) ? (await read(`.orchestrator/wave-dispatch-scopes.${sid}.json`, true)).value : null;
+  const dispatchWave = positive(Number(String(dispatch?.waveKey ?? '').match(/\|w(\d+)\|/)?.[1]));
+  const currentDispatch = dispatch && waveNumber && dispatchWave === waveNumber && Array.isArray(dispatch.agents) ? dispatch : null;
+  const entries = new Map();
+  for (const a of currentDispatch?.agents ?? []) {
+    if (!text(a?.id)) continue;
+    entries.set(a.id, { id: a.id, typ: text(a.typ ?? a.agent_type ?? a.type), modellfamilie: text(a.modellfamilie ?? a.model), status: null, tokens: null, letzter_request_at: null, quelle: 'dispatch' });
+  }
+  for (const [id, a] of Object.entries(agentStatus.entries ?? {})) {
+    // Unbound/foreign status cannot make the current wave look alive.
+    if (!sid || (a.session_id ?? a.sessionId) !== sid) continue;
+    if (waveNumber && (a.wave ?? a.wave_number) !== waveNumber) continue;
+    const existing = entries.get(id);
+    entries.set(id, { id, typ: text(a.agent_type) ?? existing?.typ ?? null, modellfamilie: text(a.model) ?? existing?.modellfamilie ?? null,
+      status: text(a.status ?? a.text), tokens: null, letzter_request_at: null, quelle: existing ? 'dispatch+agent-status' : 'agent-status' });
+  }
+  if (agentStatus.degraded) degraded.push('agents:degraded');
+  const events = parseEvents(eventsRead.text ?? '');
+  const gates = events.filter(e => (e.event ?? e.event_type).startsWith('orchestrator.quality_gate.'));
+  const lastGate = gates.reduce((last, event) => {
+    const next = gateFromEvent(event);
+    return last?.passed === false && next.passed === null ? last : next;
+  }, null);
+  const lockLive = lock ? readers.isLockLive(lock, now) : false;
+  const sessionLockLive = lockLive && sid !== null && lock.session_id === sid;
+  const latest = name => events.filter(e => (e.event ?? e.event_type) === name && e.dry_run !== true).at(-1);
+  const mirror = latest('orchestrator.vault.mirror_run_completed');
+  const board = latest('orchestrator.vault.board_written');
+  const peers = await Promise.all((discovery.sessions ?? []).filter(s => s.sessionId !== sid).map(async s => {
+    const root = s.worktreePath;
+    const peerRead = async file => { try { return JSON.parse(await readers.readText(path.join(root, file))); } catch { return null; } };
+    const peerLock = (await readers.lock(root)).lock;
+    const peerStateRaw = await readers.readText(path.join(root, '.claude/STATE.md')).catch(() => null);
+    const peerFm = parseStateMd(peerStateRaw)?.frontmatter;
+    const bound = peerFm?.['session-id'] === s.sessionId;
+    const stateWave = bound ? positive(peerFm['current-wave']) : null;
+    const pd = safeId(s.sessionId) ? await peerRead(`.orchestrator/wave-dispatch-scopes.${s.sessionId}.json`) : null;
+    const dispatchNumber = pd?.waveKey?.startsWith(`${s.sessionId}|`) ? positive(Number(pd.waveKey.split('|')[1]?.slice(1))) : null;
+    const currentWave = stateWave ?? dispatchNumber;
+    const aggregate = currentWave ? await peerRead(`.claude/filescopes/wave-${currentWave}.scopes.json`) : null;
+    return { session_id: s.sessionId, branch: text(s.branch), status: bound ? text(peerFm.status) : null,
+      current_wave: currentWave, last_heartbeat: peerLock?.session_id === s.sessionId ? text(peerLock.last_heartbeat) : text(s.last_heartbeat),
+      gleiches_working_copy: path.resolve(root) === path.resolve(repoRoot), scope_paths: dispatchNumber !== null && dispatchNumber !== currentWave ? null : scopePaths(aggregate, pd) };
+  }));
+  return {
+    schema_version: 1, measured_at: new Date(now).toISOString(), repo: { root: repoRoot, name: path.basename(repoRoot) },
+    lock: lock ? { session_id: text(lock.session_id), live: lockLive, last_heartbeat: text(lock.last_heartbeat) } : null,
+    session: sid ? { session_id: sid, semantic_session_id: text(lock?.semantic_session_id) } : null,
+    wave: { running: waveRead.absent ? false : ownWave ? sessionLockLive : null, number: waveNumber, role: text(ownWave?.role),
+      agents_total: Array.isArray(currentDispatch?.agents) ? currentDispatch.agents.length : null, source: ownWave ? '.claude/wave-scope.json' : null },
+    agents: { entries: [...entries.values()], source: agentStatus.source ?? (currentDispatch ? 'dispatch' : null), at: agentStatus.at ?? text(currentDispatch?.updated), degraded: agentStatus.degraded ?? null },
+    state: { status: text(state.status), session_type: text(state['session-type'] ?? state.type ?? state.mode), current_wave: positive(state['current-wave']), total_waves: positive(state['total-waves'] ?? state.waves) },
+    gate: { last: lastGate, last_green_sha: typeof greenRead.value === 'string' && /^[a-f0-9]{7,64}$/i.test(greenRead.value.trim()) ? greenRead.value.trim() : null },
+    peers, vault: { enabled: config.enabled ?? null, mode: config.mode ?? null,
+      last_run: mirror ? { at: text(mirror.timestamp), created: number(mirror.created), updated: number(mirror.updated), failed: number(mirror.failed), aborted: mirror.aborted ?? null } : null,
+      board: board ? { action: text(board.action), at: text(board.timestamp) } : null }, degraded: [...new Set(degraded)],
+  };
+}

package/scripts/lib/so-hud/runtime.mjs

@@ -0,0 +1,76 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { discoverActiveSessions } from '../session-discovery.mjs';
+import { readRegistry, activeDir } from '../session-registry.mjs';
+import { readCurrentStatus } from '../agent-status.mjs';
+import { readLockDetailed, isLockLive } from '../session-lock.mjs';
+import { readTailWindow } from '../tail-window.mjs';
+import { parseSessionConfig } from '../config.mjs';
+import { resolveStateMdPath } from '../state-md.mjs';
+import { collectSnapshot } from './collect.mjs';
+const exec = promisify(execFile);
+export const MAX_EVENT_BYTES = 512 * 1024;
+
+export function readEventTail(repoRoot) {
+  try {
+    const tail = readTailWindow(path.join(repoRoot, '.orchestrator/metrics/events.jsonl'), MAX_EVENT_BYTES);
+    return { text: tail.cut ? tail.text.slice(tail.text.indexOf('\n') + 1) : tail.text, degraded: tail.cut ? ['events:tail-only'] : [] };
+  } catch (e) { return { text: '', degraded: [e.code === 'ENOENT' ? 'events:absent' : 'events:unreadable'] }; }
+}
+
+async function registryWithHealth() {
+  // The canonical reader intentionally swallows failures; distinguish its directory first.
+  try { await fs.readdir(activeDir()); }
+  catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+  return readRegistry();
+}
+
+/** Capture fallback at the injected boundaries, without intercepting global stderr. */
+export async function discover(repoRoot, { run = exec, registry = registryWithHealth, discovery = discoverActiveSessions, now = Date.now() } = {}) {
+  const degraded = [];
+  let registryEntries = [];
+  const sessions = await discovery(repoRoot, {
+    now, timeoutMs: 1000,
+    listWorktreesImpl: async () => {
+      try {
+        const { stdout } = await run('git', ['-C', repoRoot, 'worktree', 'list', '--porcelain'], { timeout: 700, maxBuffer: 512 * 1024 });
+        return stdout.trim().split('\n\n').filter(Boolean).map(block => {
+          const lines = block.split('\n');
+          return { path: lines.find(l => l.startsWith('worktree '))?.slice(9), branch: lines.find(l => l.startsWith('branch '))?.slice(7).replace(/^refs\/heads\//, '') ?? '' };
+        }).filter(w => w.path);
+      } catch (e) {
+        degraded.push(e.killed || e.code === 'ETIMEDOUT' ? 'discovery-timeout' : 'discovery-fallback');
+        return [{ path: repoRoot, branch: '' }];
+      }
+    },
+    registryReader: async () => {
+      try { registryEntries = await registry(); return registryEntries; } catch { degraded.push('registry-unreadable'); return []; }
+    },
+  });
+  if (sessions.some(s => s.registryOnly)) degraded.push('discovery:registry-fallback');
+  return { sessions: sessions.map(s => ({ ...s, last_heartbeat: registryEntries.find(r => r.session_id === s.sessionId)?.last_heartbeat ?? null })), degraded };
+}
+
+async function config(repoRoot) {
+  for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+    try {
+      const source = await fs.readFile(path.join(repoRoot, name), 'utf8');
+      if (!/^vault-integration:/m.test(source)) continue;
+      // No host-local owner.yaml reads and no vault path resolution outside this repo.
+      const parsed = parseSessionConfig(source, { hostPaths: { env: {}, ownerConfig: {} } });
+      const value = parsed['vault-integration'];
+      return { enabled: value?.enabled ?? null, mode: value?.mode ?? null };
+    } catch (e) { if (e.code !== 'ENOENT') return { degraded: ['config:unreadable'] }; }
+  }
+  return { enabled: null, mode: null };
+}
+export async function measure(repoRoot) {
+  return collectSnapshot(repoRoot, {
+    now: Date.now, readText: file => fs.readFile(file, 'utf8'), lock: root => readLockDetailed({ repoRoot: root }),
+    isLockLive, agents: root => readCurrentStatus({ repoRoot: root }), discover, events: readEventTail, config,
+    statePath: path.relative(repoRoot, resolveStateMdPath(repoRoot)),
+    sessionId: process.env.CLAUDE_SESSION_ID ?? process.env.SO_SESSION_ID ?? null,
+  });
+}

package/scripts/lib/state-md/idle-reset.mjs

@@ -0,0 +1,239 @@
+/**
+ * Idle Reset for STATE.md (issue #1560) — the code form of session-start
+ * Phase 1.5 § "Idle Reset" (skills/session-start/references/phase-1-5-session-continuity.md).
+ *
+ * Until #1560 the reset existed only as prose and every coordinator rewrote
+ * STATE.md by hand. Its Rule 6 deleted the five recommendation keys from the
+ * frontmatter, which is exactly what Phase 7.5's `buildLiveSignals()` reads —
+ * so after every clean `/close` the Mode-Selector saw no recommendation and
+ * fell back to `feature` at confidence 0. The keys now STAY in the frontmatter:
+ * they are the session-to-session handoff, and session-end Phase 3.7a (their
+ * sole writer) overwrites them at the next close.
+ *
+ * Deliberately NOT re-exported from `scripts/lib/state-md.mjs`: that barrel is
+ * part of the hook import closure (`hooks/_lib/hook-import-set.json`), and no
+ * hook needs the reset. The CLI `scripts/state-md-idle-reset.mjs` imports this
+ * module directly.
+ */
+
+import { parseStateMd, serializeStateMd } from './yaml-parser.mjs';
+import { existsSync } from 'node:fs';
+import { resolveStateMdPath, updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mjs';
+import { parseRecommendations } from './recommendations.mjs';
+
+/** Rule 7: the drift-baseline keys that must not survive into session N+1. */
+const SCOPE_BASELINE_KEYS = [
+  'scope-baseline-intent',
+  'scope-baseline-owner-boundary',
+  'scope-baseline-planned-files',
+  'scope-baseline-session',
+  'scope-baseline-frozen-at',
+];
+
+/** A level-2 heading (`## X`), never a deeper one (`### X`). */
+const H2_RE = /^##(?!#)\s/;
+
+/** Rule 6: heading of the human-readable recommendations copy. */
+const RECOMMENDATIONS_HEADING = '### Recommendations (archived from v1.1 frontmatter)';
+
+/**
+ * Splits a STATE.md body into the text before the first level-2 heading and
+ * one record per level-2 section. Every record keeps its raw lines (heading
+ * included, up to the next level-2 heading), so re-joining an untouched
+ * section is byte-identical.
+ *
+ * KNOWN CEILING: a `## ` line inside a fenced code block is read as a heading,
+ * the same limitation every helper in body-sections.mjs shares. No STATE.md
+ * section observed so far carries fenced code.
+ *
+ * @param {string} body
+ * @returns {{preamble: string[], sections: Array<{heading: string, lines: string[]}>}}
+ */
+function splitSections(body) {
+  const preamble = [];
+  const sections = [];
+  for (const line of body.split('\n')) {
+    if (H2_RE.test(line)) sections.push({ heading: line, lines: [line] });
+    else if (sections.length === 0) preamble.push(line);
+    else sections[sections.length - 1].lines.push(line);
+  }
+  return { preamble, sections };
+}
+
+/** @param {string} heading @param {string} title */
+function isSection(heading, title) {
+  // The title must END there (or open a parenthesis): `## Wave History Archive`
+  // is a different section.
+  return new RegExp(`^##\\s+${title}(?:\\s*\\(|\\s*$)`).test(heading);
+}
+
+/** Drops leading and trailing blank lines. */
+function trimBlankLines(lines) {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === '') start++;
+  while (end > start && lines[end - 1].trim() === '') end--;
+  return lines.slice(start, end);
+}
+
+/** @param {number} x  a ratio in 0..1 */
+function pct(x) {
+  return `${Math.round(x * 100)}%`;
+}
+
+/**
+ * Rule 6: the human-readable copy of the recommendation fields. Null fields
+ * are omitted; `null` overall when there is nothing to show.
+ *
+ * @param {object} frontmatter
+ * @returns {string|null}
+ */
+function renderRecommendationsBlock(frontmatter) {
+  const rec = parseRecommendations(frontmatter);
+  if (rec === null) return null;
+  const bullets = [];
+  if (rec.mode !== null) bullets.push(`- **Recommended mode:** ${rec.mode}`);
+  if (rec.rationale !== null) bullets.push(`- **Rationale:** ${rec.rationale}`);
+  if (rec.completionRate !== null) bullets.push(`- **Completion rate:** ${pct(rec.completionRate)}`);
+  if (rec.carryoverRatio !== null) bullets.push(`- **Carryover ratio:** ${pct(rec.carryoverRatio)}`);
+  if (rec.priorities !== null) {
+    const list = rec.priorities.length > 0 ? rec.priorities.map((id) => `#${id}`).join(', ') : 'none';
+    bullets.push(`- **Top priorities:** ${list}`);
+  }
+  if (bullets.length === 0) return null;
+  return [RECOMMENDATIONS_HEADING, ...bullets].join('\n');
+}
+
+/**
+ * Removes one `### <heading>` subsection (up to the next `### ` or `## ` line).
+ *
+ * @param {string[]} lines
+ * @param {string} heading  the full `### …` line
+ * @returns {string[]}
+ */
+function dropSubsection(lines, heading) {
+  const out = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (line.trimEnd() === heading) skipping = true;
+    else if (skipping && /^#{2,3}\s/.test(line)) skipping = false;
+    if (!skipping) out.push(line);
+  }
+  return out;
+}
+
+/**
+ * Resets a `status: completed` STATE.md to idle (Phase 1.5 § Idle Reset,
+ * Rules 1-7). Pure: string in, result out, no file I/O.
+ *
+ * 1. `status: idle`. 2. `current-wave: 0`. 3. Every `## Wave History` body moves
+ * into a new `## Previous Session` section (appended at the end of the body,
+ * replacing any earlier one) under `### Wave History (<session>)`; the original
+ * section is removed. 4. `## Deviations` keeps its heading with an empty body;
+ * `## What Not To Retry` and `## Open Questions` stay byte-for-byte. 5. Other
+ * frontmatter keys are untouched. 6. The five recommendation keys STAY in the
+ * frontmatter (Phase 7.5 reads them); a readable copy heads `## Previous Session`.
+ * 7. The five `scope-baseline-*` keys are deleted, no other key.
+ *
+ * When neither a Wave History section nor a recommendation exists, an existing
+ * `## Previous Session` is left as it is — there is nothing to replace it with.
+ * With recommendations but no Wave History (a coordinator-direct session), the
+ * earlier archive body stays below the new recommendations block.
+ *
+ * @param {string} contents  STATE.md contents
+ * @returns {{changed: boolean, contents: string, reason?: 'status-not-completed'|'unparseable'}}
+ */
+export function resetStateMdToIdle(contents) {
+  const parsed = parseStateMd(contents);
+  if (parsed === null) return { changed: false, contents, reason: 'unparseable' };
+  if (parsed.frontmatter.status !== 'completed') {
+    return { changed: false, contents, reason: 'status-not-completed' };
+  }
+
+  const { preamble, sections } = splitSections(parsed.body);
+  const waveHistory = sections.filter((s) => isSection(s.heading, 'Wave History'));
+  const recBlock = renderRecommendationsBlock(parsed.frontmatter);
+  const archive = waveHistory.length > 0 || recBlock !== null;
+  // Rule 6 PREPENDS: without a new Wave History, the earlier archive stays below
+  // the fresh recommendations block (minus its own, now superseded, copy).
+  const keptArchive =
+    waveHistory.length === 0
+      ? trimBlankLines(
+          dropSubsection(
+            sections.filter((s) => isSection(s.heading, 'Previous Session')).flatMap((s) => s.lines.slice(1)),
+            RECOMMENDATIONS_HEADING,
+          ),
+        )
+      : [];
+
+  const lines = [...preamble];
+  for (const { heading, lines: own } of sections) {
+    if (isSection(heading, 'Wave History')) continue;
+    if (archive && isSection(heading, 'Previous Session')) continue;
+    lines.push(...(isSection(heading, 'Deviations') ? [heading, ''] : own));
+  }
+
+  let body = lines.join('\n');
+  if (archive) {
+    const blocks = [];
+    if (recBlock !== null) blocks.push(recBlock);
+    if (waveHistory.length > 0) {
+      const session = typeof parsed.frontmatter.session === 'string' ? parsed.frontmatter.session : '';
+      const heading = session ? `### Wave History (${session})` : '### Wave History';
+      const moved = trimBlankLines(waveHistory.flatMap((s) => s.lines.slice(1)));
+      blocks.push([heading, ...moved].join('\n'));
+    }
+    if (keptArchive.length > 0) blocks.push(keptArchive.join('\n'));
+    // Only ever ADD newlines before the new section — trimming would change the
+    // trailing bytes of whatever section now precedes it (possibly WNTR).
+    if (body.length > 0 && !body.endsWith('\n\n')) body += body.endsWith('\n') ? '\n' : '\n\n';
+    body += `## Previous Session\n\n${blocks.join('\n\n')}\n`;
+  }
+
+  const fields = { status: 'idle', 'current-wave': 0 };
+  for (const key of SCOPE_BASELINE_KEYS) fields[key] = null;
+  const next = updateFrontmatterFields(
+    serializeStateMd({ frontmatter: parsed.frontmatter, body }),
+    fields,
+  );
+  return { changed: next !== contents, contents: next };
+}
+
+/**
+ * Applies `resetStateMdToIdle` to the repo's STATE.md under the STATE.md lock
+ * (`writeStateMd`). A missing or empty STATE.md is a no-op with reason `missing`.
+ * A write the size-ceiling / frontmatter-safe guards refuse comes back as
+ * `changed: false` with that guard's reason.
+ *
+ * @param {string} repoRoot  absolute repository root (required)
+ * @param {object} [opts]    passed through to `writeStateMd`
+ * @returns {Promise<{changed: boolean, reason?: string, path: string}>}
+ * @throws {Error} when repoRoot is missing
+ */
+export async function resetStateMdToIdleOnDisk(repoRoot, opts = {}) {
+  if (!repoRoot) {
+    throw new Error(`resetStateMdToIdleOnDisk: repoRoot is required (got ${typeof repoRoot}).`);
+  }
+  // No STATE.md: answer before the lock, which would otherwise create
+  // <repoRoot>/.orchestrator/ in whatever directory a mistyped root names.
+  const statePath = resolveStateMdPath(repoRoot);
+  if (!existsSync(statePath)) return { changed: false, reason: 'missing', path: statePath };
+  let reason;
+  const result = await writeStateMd(
+    repoRoot,
+    (contents) => {
+      if (contents === '') {
+        reason = 'missing';
+        return null;
+      }
+      const reset = resetStateMdToIdle(contents);
+      reason = reset.reason;
+      return reset.changed ? reset.contents : null;
+    },
+    opts,
+  );
+  const out = { changed: result.written, path: result.path };
+  const why = result.reason ?? reason;
+  if (why !== undefined) out.reason = why;
+  return out;
+}

package/scripts/lib/state-md/recommendations.mjs

@@ -37,10 +37,7 @@ export function parseRecommendations(frontmatter) {
   const mode = typeof frontmatter['recommended-mode'] === 'string'
     ? frontmatter['recommended-mode']
     : null;
-  const priorities = Array.isArray(frontmatter['top-priorities'])
-    && frontmatter['top-priorities'].every((x) => Number.isInteger(x))
-    ? frontmatter['top-priorities'].slice()
-    : null;
+  const priorities = parsePriorities(frontmatter['top-priorities']);
   const carryoverRatio = typeof frontmatter['carryover-ratio'] === 'number'
     && !Number.isNaN(frontmatter['carryover-ratio'])
     ? frontmatter['carryover-ratio']
@@ -55,3 +52,28 @@ export function parseRecommendations(frontmatter) {
 
   return { mode, priorities, carryoverRatio, completionRate, rationale };
 }
+
+/** An entry that is exactly an issue reference of THIS repo: `42` or `#42`. */
+const ISSUE_REF_RE = /^#?\d+$/;
+
+/**
+ * Normalises `top-priorities` to issue numbers. Integers pass; strings that are
+ * exactly an issue ref (`"#42"`, `"42"`) become integers; every other entry is
+ * dropped. A hand-written `"#370 fix banner"` or `"other-repo#74"` is never
+ * mined for digits, because the number may belong to another repo. An array
+ * that held entries but keeps none is a type mismatch (`null`), as before.
+ *
+ * @param {unknown} raw
+ * @returns {number[]|null}
+ */
+function parsePriorities(raw) {
+  if (!Array.isArray(raw)) return null;
+  const ids = [];
+  for (const entry of raw) {
+    if (Number.isInteger(entry)) ids.push(entry);
+    else if (typeof entry === 'string' && ISSUE_REF_RE.test(entry.trim())) {
+      ids.push(Number.parseInt(entry.trim().replace('#', ''), 10));
+    }
+  }
+  return raw.length > 0 && ids.length === 0 ? null : ids;
+}

package/scripts/lib/subagents-schema.mjs

@@ -55,6 +55,8 @@
  *   total_cost_usd    number  | null — native total cost in USD (#624, fractional,
  *                                      best-effort: null when the harness does not
  *                                      expose it; no rate table is applied)
+ *   cost_basis        'api-list-equivalent' | null — explicitly supplied cost
+ *                                      provenance; null means unknown (#1543)
  *
  * OTel aliases (optional, stop-only, additive — #411, schema_version=1 backwards-compat):
  *   gen_ai.usage.input_tokens   integer | null — RAW UNCACHED prompt tokens (OTel
@@ -69,6 +71,7 @@
 import { readFile, appendFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { COST_BASIS } from './telemetry/pricing.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -267,6 +270,11 @@ export function validateSubagent(entry, options = {}) {
     }
   }
 
+  // #1543 additive: never infer provenance from a native dollar value.
+  if (entry.cost_basis !== undefined && entry.cost_basis !== null && entry.cost_basis !== COST_BASIS) {
+    throw new ValidationError(`cost_basis must be ${COST_BASIS} or null`, 'cost_basis');
+  }
+
   // OTel alias — #411 additive, schema_version=1 backwards-compat
   const otelInputTokens = entry['gen_ai.usage.input_tokens'];
   if (otelInputTokens !== undefined && otelInputTokens !== null) {
@@ -334,6 +342,7 @@ export function normalizeSubagent(entry) {
     model: entry.model ?? null,
     // total_cost_usd — #624 additive, best-effort native cost (null when absent)
     total_cost_usd: entry.total_cost_usd ?? null,
+    cost_basis: entry.cost_basis ?? null,
     // OTel alias — #411 additive, schema_version=1 backwards-compat
     'gen_ai.usage.input_tokens': entry['gen_ai.usage.input_tokens'] ?? null,
     'gen_ai.usage.cache_read_input_tokens': entry['gen_ai.usage.cache_read_input_tokens'] ?? null,

package/scripts/lib/telemetry/pricing.mjs

@@ -62,6 +62,17 @@
  */
 export const PRICING_TABLE_DATE = '2026-09-29';
 
+/**
+ * What a dollar figure computed from this table IS (#1470 Pkt 4): the API
+ * list-price equivalent of the metered tokens — never a payment. Subscription
+ * quota, purchased credits and what was actually billed are not visible to
+ * this module, so a consumer must not present the figure as any of them.
+ * Written beside every persisted cost as `cost_basis`; the session validator's
+ * `COST_BASES` must contain it (pinned by tests/scripts/emit-session.test.mjs).
+ * @type {'api-list-equivalent'}
+ */
+export const COST_BASIS = 'api-list-equivalent';
+
 /**
  * @typedef {Object} PricingRow
  * @property {number} input           - USD per 1M uncached prompt tokens.

package/scripts/lib/vault-mirror/namespace.mjs

@@ -55,7 +55,7 @@
 
 import { basename, resolve } from 'node:path';
 
-import { subjectToSlug } from './utils.mjs';
+import { legacySubjectToSlug } from './utils.mjs';
 import { isOwnerLeakySegment } from '../../lib/validate/check-owner-leakage.mjs';
 import { loadPseudonymMap } from './pseudonym-map.mjs';
 import { loadHostPaths, resolveHostPath } from '../config/host-paths.mjs';
@@ -311,7 +311,8 @@ export function resolveRepoNamespace({ vaultName = null, repoRoot = null } = {})
     : (declaredSlug ?? deriveRepo({ repoRoot: root }));
 
   // Sanitise: collapse to last path segment, lowercase, strip non-[a-z0-9-].
-  const seg = subjectToSlug(base);
+  // Repository storage identity stays historical; only new note names transliterate.
+  const seg = legacySubjectToSlug(base);
 
   // Leak-guard: check both the raw base AND the sanitised segment.
   // A personal home path or a private project slug must be caught before writing