session-orchestrator 5.3.0 → 5.4.0

package/scripts/baseline-archetypes.mjs

@@ -10,7 +10,7 @@ export async function main(argv = process.argv.slice(2)) {
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
     if (arg === '--help' || arg === '-h') {
-      process.stdout.write('Usage: node scripts/baseline-archetypes.mjs [--repo PATH] [--archetype ID]\nOffline, read-only JSON lookup. Exit 0: public/private; exit 2: invalid configuration or contract.\n');
+      process.stdout.write('Usage: node scripts/baseline-archetypes.mjs [--repo PATH] [--archetype ID]\nOffline, read-only JSON lookup. Exit 0: public/private; exit 2: invalid configuration or contract.\nExit 2 reason producer-missing: the baseline directory exists but has no scripts/archetype-manifest.mjs exporter.\n');
       return 0;
     }
     if (!['--repo', '--archetype'].includes(arg) || !argv[index + 1] || argv[index + 1].startsWith('--')) {

package/scripts/check-package-manager.mjs

@@ -25,6 +25,11 @@
 //            (warn locally; upgraded to a hard failure under CI)
 //        c1  pnpm-lock.yaml must NOT be tracked in git
 //        c2  package-lock.json MUST be tracked in git
+//   3. Husky activation (#1458, advisory only — never affects `ok`/exit code):
+//        h1  `.husky/` exists but git core.hooksPath is not `.husky/_` — the
+//            `prepare: husky` script never ran because ignore-scripts=true,
+//            so commit-msg/pre-commit/pre-push are inactive. Warns locally
+//            and recommends `npx husky`; silent under CI.
 //
 // SCOPE GUARD:
 //   This script only guards the REPOSITORY ROOT package.json. If invoked
@@ -64,8 +69,8 @@
 // on any dependency install).
 
 import { existsSync, lstatSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { dirname, isAbsolute, join, posix, resolve } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { isMainModule } from './lib/is-main-module.mjs';
 
@@ -266,11 +271,53 @@ export function parseCiEnv(value) {
   return !['', '0', 'false', 'no'].includes(normalized);
 }
 
+/** One-line stderr WARN for an inactive Husky install (#1458). */
+export const HUSKY_INACTIVE_WARNING =
+  '⚠ check-package-manager: git core.hooksPath is not set to .husky/_ — Husky hooks (commit-msg, pre-commit, pre-push) are INACTIVE in this clone because .npmrc ignore-scripts=true skips the prepare script (#1458). Run: npx husky';
+
+/**
+ * Advisory check (#1458): `.npmrc` `ignore-scripts=true` (SEC-020) means the
+ * `prepare: husky` script never runs on `npm ci`, so a fresh clone has no
+ * `core.hooksPath` and every Husky hook is silently inactive. This only
+ * REPORTS the state — it never runs `npx husky`, never writes git config and
+ * never affects the guard's `ok`/exit code. Silent under CI.
+ * @param {string} repoRoot
+ * @param {{ env?: NodeJS.ProcessEnv, ci?: boolean }} [opts] — `env` is also
+ *   passed to the git subprocess (lets tests isolate from global git config).
+ * @returns {{ hooksPath: string, active: boolean, skipped: 'ci'|'no-husky-dir'|null }}
+ */
+export function checkHuskyHooksPath(repoRoot, { env = process.env, ci } = {}) {
+  if (ci ?? parseCiEnv(env.CI)) return { hooksPath: '', active: false, skipped: 'ci' };
+  if (!existsSync(join(repoRoot, '.husky'))) {
+    return { hooksPath: '', active: false, skipped: 'no-husky-dir' };
+  }
+
+  let hooksPath;
+  try {
+    hooksPath = execFileSync('git', ['-C', repoRoot, 'config', '--get', 'core.hooksPath'], {
+      encoding: 'utf8',
+      env,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    // Non-zero exit (key unset) or git unavailable — treat as unset.
+    hooksPath = '';
+  }
+
+  const norm = hooksPath.replace(/\\/g, '/').replace(/\/+$/, '');
+  const active =
+    norm !== '' &&
+    (isAbsolute(hooksPath) ? norm.endsWith('/.husky/_') : posix.normalize(norm) === '.husky/_');
+
+  return { hooksPath, active, skipped: null };
+}
+
 /**
  * Runs the full guard and returns a plain-object result. Pure(ish) — the
  * only side effects are read-only fs/git calls. Never throws or exits.
- * @param {{ cwd?: string, ci?: boolean, allowMissingNodeModules?: boolean, repoRoot?: string }} [opts]
- * @returns {{ ok: boolean, ci: boolean, skipped: boolean, repoRoot: string, findings: Array<{code: string, severity: string, effectiveSeverity: string, message: string}> }}
+ * `hooks` carries the advisory Husky check (#1458); it never affects `ok`.
+ * @param {{ cwd?: string, ci?: boolean, allowMissingNodeModules?: boolean, repoRoot?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {{ ok: boolean, ci: boolean, skipped: boolean, repoRoot: string, findings: Array<{code: string, severity: string, effectiveSeverity: string, message: string}>, hooks?: { hooksPath: string, active: boolean, skipped: 'ci'|'no-husky-dir'|null } }}
  */
 export function runPackageManagerGuard(opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
@@ -302,7 +349,9 @@ export function runPackageManagerGuard(opts = {}) {
 
   const ok = !findings.some((f) => f.effectiveSeverity === 'error');
 
-  return { ok, ci, skipped: false, repoRoot, findings };
+  const hooks = checkHuskyHooksPath(repoRoot, { env: opts.env ?? process.env, ci });
+
+  return { ok, ci, skipped: false, repoRoot, findings, hooks };
 }
 
 // ---------------------------------------------------------------------------
@@ -332,6 +381,9 @@ CHECKS
         (warn locally; upgraded to a hard failure under CI, fail-closed)
     c1  pnpm-lock.yaml must NOT be tracked in git
     c2  package-lock.json MUST be tracked in git
+  Husky activation (advisory, never changes the exit code; silent under CI):
+    h1  .husky/ exists but git core.hooksPath is not .husky/_ (#1458) —
+        run \`npx husky\` once (ignore-scripts=true skips \`prepare\`)
 
 OPTIONS
   --allow-missing-node-modules  Document that node_modules may not exist yet
@@ -412,6 +464,11 @@ if (isMain) {
 
   const result = runPackageManagerGuard({ allowMissingNodeModules: opts.allowMissingNodeModules });
 
+  // Advisory only (#1458) — never changes the exit code.
+  if (result.hooks && !result.hooks.active && result.hooks.skipped === null) {
+    console.error(HUSKY_INACTIVE_WARNING);
+  }
+
   if (opts.json) {
     console.log(JSON.stringify(result));
     process.exit(result.ok ? 0 : 1);

package/scripts/cursor-install.mjs

@@ -20,6 +20,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { CURSOR_TO_CANONICAL_EVENT } from './lib/cursor-hook-bridge.mjs';
+import { shellQuote as shQuote } from './lib/sh-quote.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const SCRIPT_DIR = path.dirname(__filename);
@@ -62,10 +63,6 @@ function _isDir(p) {
   try { return statSync(p).isDirectory(); } catch { return false; }
 }
 
-function shQuote(value) {
-  return `'${String(value).replace(/'/g, `'\\''`)}'`;
-}
-
 function linkPath(source, dest, label) {
   mkdirSync(path.dirname(dest), { recursive: true });
   if (_isSymlink(dest)) {

package/scripts/emit-session.mjs

@@ -6,12 +6,15 @@
  * a single session record to `.orchestrator/metrics/sessions.jsonl` (or any
  * target path). Replaces the raw shell `>>` append with a validated path:
  *
- *   node scripts/emit-session.mjs [--file PATH] [--entry JSON]
+ *   node scripts/emit-session.mjs [--file PATH] [--entry JSON] [--session-uuid ID]
  *
  * Input modes:
  *   --entry '<json>'   pass the entry JSON literally (for shell pipelines)
  *   (stdin)            read the entry JSON from stdin (default when no --entry)
  *
+ *   --session-uuid ID  this session's raw harness UUID (overrides the
+ *                      current-session.json lookup; the test seam)
+ *
  * Defaults:
  *   --file .orchestrator/metrics/sessions.jsonl
  *
@@ -33,6 +36,8 @@ import {
   stampMemoryCleanup,
 } from './lib/memory-cleanup-stamp.mjs';
 import { parseStateMd, readSessionProfile, resolveStateMdPath } from './lib/state-md.mjs';
+import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
+import { rollupSessionTokens } from './lib/session-token-rollup.mjs';
 import { serializeSessionLineChecked } from './lib/session-schema/serializer.mjs';
 import {
   validateSession,
@@ -50,17 +55,158 @@ export { serializeSessionLineChecked };
 // ref (`HEAD`, a branch) would resolve to a DIFFERENT commit when read later.
 const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 
+// Rollup fields merged into the record (#1436) — the totals plus the #1244
+// cache buckets and contract marker the former prose recipe merged, and the
+// #1475 cost-coverage counters, which say why `total_cost_usd` is absent when
+// priced < total. `legacy_v1_records` stays in the rollup's own return value.
+const ROLLUP_KEYS = Object.freeze([
+  'total_tokens',
+  'total_token_input',
+  'total_token_output',
+  'total_token_input_uncached',
+  'total_token_cache_read',
+  'total_token_cache_creation',
+  'total_cost_usd',
+  'subagents_with_tokens',
+  'matched_records',
+  'cost_records_priced',
+  'cost_records_total',
+  '_token_schema',
+]);
+
+// Rollup keys validateSession() requires to be non-negative integers.
+const INTEGER_ROLLUP_KEYS = new Set([
+  'total_tokens',
+  'matched_records',
+  'cost_records_priced',
+  'cost_records_total',
+]);
+
+/**
+ * Resolve THIS session's raw harness UUID — the join key `subagents.jsonl`
+ * (`parent_session_id`) and `events.jsonl` (`session_id`) carry, which the
+ * record itself does not (its `session_id` is the semantic slug).
+ *
+ * `--session-uuid` wins (an explicit assertion, and the test seam). Otherwise
+ * `.orchestrator/current-session.json` is read. That file is SHARED by the
+ * working copy — the last SessionStart hook wrote it — so its UUID is adopted
+ * ONLY when its `semantic_session_id` (or, for a legacy raw-id record, its
+ * `session_id`) equals this record's `session_id`: the same "named owner
+ * equals the record" gate as the STATE.md derivation in main(). When this
+ * process carries its own session id (`readProcessLocalSessionIds()` — the
+ * harness env, which a dispatched subagent inherits from the coordinator), that
+ * witness OUTRANKS the shared marker: a marker UUID the process does not carry
+ * was written by a peer and is refused even when the labels agree (two sessions
+ * can mint the same semantic label, #1066). Ranked, never unioned
+ * (.claude/rules/identity-and-locks.md). A foreign marker is WARNed and yields
+ * null; an absent marker yields null silently.
+ *
+ * CEILING: a resumed session that received a NEW raw id keeps its semantic id,
+ * so only the latest raw id resolves and subagents dispatched under the earlier
+ * one are not rolled up. Revisit if current-session.json gains a raw-id history.
+ *
+ * Never throws.
+ *
+ * @param {{ override: string|null, recordSessionId: unknown }} opts
+ * @returns {string|null}
+ */
+function resolveOwnSessionUuid({ override, recordSessionId }) {
+  const trimmed = (v) => (typeof v === 'string' ? v.trim() : '');
+  const explicit = trimmed(override);
+  if (explicit) return explicit;
+  const markerPath = join(process.cwd(), '.orchestrator', 'current-session.json');
+  let marker;
+  try {
+    if (!existsSync(markerPath)) return null;
+    marker = JSON.parse(readFileSync(markerPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(
+      `emit-session: WARN could not read ${markerPath} (${err?.message ?? err}); ` +
+        `omitting raw_session_id and the token rollup\n`
+    );
+    return null;
+  }
+  const uuid = trimmed(marker?.session_id);
+  if (!uuid) return null;
+  const semantic = trimmed(marker?.semantic_session_id);
+  const namesRecord = (semantic !== '' && semantic === recordSessionId) || uuid === recordSessionId;
+  const processIds = readProcessLocalSessionIds();
+  const processAgrees = processIds.length === 0 || processIds.includes(uuid);
+  if (namesRecord && processAgrees) return uuid;
+  // The record's session_id is the semantic label (STATE.md `session`); name
+  // both sides of whichever comparison failed, so the operator sees which drifted.
+  const why = namesRecord
+    ? `session label ${recordSessionId} matches, but this process runs as ` +
+      `${processIds.join('/')}, not the marker's uuid ${uuid}`
+    : `session label mismatch: marker semantic_session_id=${semantic || '<absent>'} ` +
+      `vs record session_id=${recordSessionId ?? '<unknown>'}`;
+  process.stderr.write(
+    `emit-session: WARN current-session.json ${why}; omitting raw_session_id and the token rollup\n`
+  );
+  return null;
+}
+
+/**
+ * The `head_sha` of THIS session's own `orchestrator.session.started` event —
+ * matched on the raw UUID, so a parallel session's start event never supplies
+ * it. The FIRST own event decides: a resume or compact that re-emits the event
+ * under the same raw id is not the session's start, so its sha is never taken —
+ * not even when the first own event carries none. Returns null when there is no
+ * own event, or the first one's head_sha is absent or not a full sha.
+ *
+ * LIMIT — rotation (#1457 point 3): events.jsonl rotates at SessionStart once
+ * it exceeds `events-rotation.max-size-mb` (default 10), and when that start is
+ * a compact/resume of THIS session the first SURVIVING own event can be a
+ * compact/resume re-emit whose head_sha is later than the real start. When the
+ * first own event carries `native_source` 'compact' or 'resume' it is provably
+ * not the start, so this returns null (unknown) rather than a wrong ref. An
+ * event without `native_source` (Codex/Cursor, or a pre-#1091 writer) is still
+ * taken — so a rotation that leaves an unlabelled re-emit first stays wrong.
+ *
+ * Whole-file read, like deriveMemoryCleanupSignal() on the same file — fine at
+ * today's events.jsonl size; revisit if the file outgrows a single read.
+ *
+ * Never throws.
+ *
+ * @param {string} eventsFile
+ * @param {string} uuid
+ * @returns {string|null}
+ */
+function readOwnStartHeadSha(eventsFile, uuid) {
+  let raw;
+  try {
+    raw = readFileSync(eventsFile, 'utf8');
+  } catch {
+    return null;
+  }
+  for (const line of raw.split('\n')) {
+    if (!line.includes(uuid)) continue;
+    let ev;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (ev?.event !== 'orchestrator.session.started' || ev.session_id !== uuid) continue;
+    if (ev.native_source === 'compact' || ev.native_source === 'resume') return null;
+    return typeof ev.head_sha === 'string' && FULL_SHA_RE.test(ev.head_sha) ? ev.head_sha : null;
+  }
+  return null;
+}
+
 function parseArgs(argv) {
-  const args = { file: '.orchestrator/metrics/sessions.jsonl', entry: null };
+  const args = { file: '.orchestrator/metrics/sessions.jsonl', entry: null, sessionUuid: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--file') args.file = argv[++i];
     else if (a === '--entry') args.entry = argv[++i];
+    else if (a === '--session-uuid') args.sessionUuid = argv[++i];
     else if (a === '--help' || a === '-h') {
       process.stdout.write(
         'Usage: node scripts/emit-session.mjs [--file PATH] [--entry JSON]\n' +
           '  --file   target JSONL file (default: .orchestrator/metrics/sessions.jsonl)\n' +
           '  --entry  entry JSON (if omitted, read from stdin)\n' +
+          '  --session-uuid  raw harness UUID (default: owned .orchestrator/current-session.json)\n' +
           'Exit codes: 0 append ok, 1 validation error, 2 I/O error\n'
       );
       process.exit(0);
@@ -131,6 +277,29 @@ async function main() {
   //      contract deliberately does not.
   repaired = normalizeWaveKeys(repaired);
 
+  // Own raw UUID (#1436), resolved once for the three derivations further down:
+  // raw_session_id, the session_start_ref events fallback, the token rollup.
+  const ownUuid = resolveOwnSessionUuid({
+    override: args.sessionUuid,
+    recordSessionId: repaired.session_id,
+  });
+
+  // An explicit session_start_ref that is not a full sha (#1443) names a
+  // DIFFERENT commit once the short form becomes ambiguous. Dropped with a WARN
+  // rather than rejected: the record is the load-bearing artefact, and the
+  // derivations below may still supply the full sha. Explicit `null` stays.
+  // Enforced HERE, not in validateSession(): the ledger already holds records
+  // with 7-char refs, and the session-start integrity banner runs every one of
+  // them through validateSession().
+  if (typeof repaired.session_start_ref === 'string' && !FULL_SHA_RE.test(repaired.session_start_ref)) {
+    process.stderr.write(
+      `emit-session: WARN session_start_ref=${repaired.session_start_ref} is not a full hex sha; ` +
+        `dropping it\n`
+    );
+    const { session_start_ref: _dropped, ...rest } = repaired;
+    repaired = rest;
+  }
+
   // `memory_cleanup_at` derivation (#699 follow-up — Disziplin statt Mechanik).
   // The flag used to be a boolean the coordinator-LLM remembered to pass at
   // session-end; it was forgotten on 2026-08-14 and the cadence marker stalled
@@ -212,6 +381,9 @@ async function main() {
   const hasOwn = (key) => Object.prototype.hasOwnProperty.call(repaired, key);
   const needsProfile = !hasOwn('session_profile');
   const needsStartRef = !hasOwn('session_start_ref');
+  // What STATE.md contributed to session_start_ref, for the WARN below when no
+  // source supplies one (#1457 point 2): none, or a ref that was discarded.
+  let stateMdStartRefNote = 'STATE.md carried none';
   if (needsProfile || needsStartRef) {
     let stateMdContents = '';
     try {
@@ -223,6 +395,7 @@ async function main() {
           `derivation (${err?.message ?? err}); omitting both\n`
       );
       stateMdContents = '';
+      stateMdStartRefNote = 'STATE.md unreadable';
     }
     // No initialiser: both the try and the catch below assign `profile`.
     let profile;
@@ -241,6 +414,7 @@ async function main() {
           `emit-session: WARN STATE.md session-start-ref=${rawRef} is not a full hex sha; ` +
             `omitting session_start_ref\n`
         );
+        stateMdStartRefNote = 'STATE.md ref discarded (not a full hex sha)';
       }
     } catch (err) {
       process.stderr.write(
@@ -249,6 +423,7 @@ async function main() {
       );
       profile = null;
       startRef = null;
+      stateMdStartRefNote = 'STATE.md unparseable';
     }
     const derived = {};
     if (needsProfile && profile !== null) derived.session_profile = profile;
@@ -258,6 +433,9 @@ async function main() {
       if (owner !== null && owner === repaired.session_id) {
         repaired = { ...repaired, ...derived };
       } else {
+        if (derived.session_start_ref !== undefined) {
+          stateMdStartRefNote = `STATE.md ref discarded (belongs to session=${owner ?? '<absent>'})`;
+        }
         // A visible omission: silence here is indistinguishable from "STATE.md
         // carries no such field", and a foreign STATE.md in this working copy
         // is precisely what the operator wants to know about.
@@ -270,6 +448,122 @@ async function main() {
     }
   }
 
+  // session_start_ref fallback (#1443): STATE.md supplied none (absent key,
+  // foreign owner, unparseable) — take the head_sha the SessionStart hook
+  // recorded on this session's own start event. Absent there too → omitted,
+  // with a WARN whether or not an own UUID was available (#1457 point 2) —
+  // without one the fallback cannot run, which is exactly when silence hid it.
+  if (!hasOwn('session_start_ref')) {
+    const headSha = ownUuid !== null
+      ? readOwnStartHeadSha(join(dirname(args.file), 'events.jsonl'), ownUuid)
+      : null;
+    if (headSha !== null) {
+      repaired = { ...repaired, session_start_ref: headSha };
+      process.stderr.write(
+        `emit-session: derived session_start_ref=${headSha} from the own orchestrator.session.started event\n`
+      );
+    } else {
+      process.stderr.write(
+        `emit-session: WARN no session_start_ref — ${stateMdStartRefNote}, ` +
+          'no own session.started head_sha available\n'
+      );
+    }
+  }
+
+  if (ownUuid !== null && !hasOwn('raw_session_id')) {
+    repaired = { ...repaired, raw_session_id: ownUuid };
+  }
+
+  // Token rollup (#1436) — mechanical, replacing the session-metrics-write.md
+  // prose step that had no production caller. Joins the sibling subagents.jsonl
+  // on the own raw UUID and fills ONLY keys the entry does not carry; an
+  // explicit `total_tokens` means the caller already rolled up, so nothing is
+  // merged. No matching records or a failed read OMITS the fields with a WARN —
+  // never a fabricated 0; a null total is omitted rather than written — for
+  // `total_cost_usd` that is any session with an unpriced subagent record
+  // (#1475: unknown model, no model, or no tokens), which the persisted
+  // `cost_records_priced < cost_records_total` then explains.
+  // match_status explains the omission; diagnostic fields stay out of the record.
+  if (ownUuid !== null && !hasOwn('total_tokens')) {
+    let rollup = null;
+    try {
+      rollup = rollupSessionTokens({
+        parentSessionId: ownUuid,
+        subagentsPath: join(dirname(args.file), 'subagents.jsonl'),
+      });
+    } catch (err) {
+      process.stderr.write(
+        `emit-session: WARN token rollup failed (${err?.message ?? err}); omitting token fields\n`
+      );
+    }
+    if (rollup !== null && rollup.matched_records > 0) {
+      const merged = {};
+      for (const key of ROLLUP_KEYS) {
+        if (hasOwn(key) || !Number.isFinite(rollup[key])) continue;
+        // Mirrors validateSession(): these two are non-negative INTEGERS, while
+        // total_token_input/output may be fractional — one fractional token
+        // value upstream must cost the field, not the record.
+        if (INTEGER_ROLLUP_KEYS.has(key) && !Number.isInteger(rollup[key])) {
+          process.stderr.write(
+            `emit-session: WARN token rollup produced an invalid field (${key} must be a ` +
+              `non-negative integer, got: ${rollup[key]}); omitting ${key}\n`
+          );
+          continue;
+        }
+        merged[key] = rollup[key];
+      }
+      // Enrichment must never be the reason the ledger gains no line: validate
+      // the enriched record first and fall back to the un-enriched one. Blamed
+      // on the rollup only when the un-enriched record validates on its own —
+      // otherwise the validation below reports the record's own defect.
+      try {
+        validateSession({ ...repaired, ...merged });
+        repaired = { ...repaired, ...merged };
+      } catch (err) {
+        if (!(err instanceof ValidationError)) throw err;
+        let baseValid = true;
+        try {
+          validateSession(repaired);
+        } catch {
+          baseValid = false;
+        }
+        if (baseValid) {
+          process.stderr.write(
+            `emit-session: WARN token rollup produced an invalid field (${err.message}); ` +
+              `omitting token fields\n`
+          );
+        }
+      }
+      if (rollup.total_tokens === null) {
+        process.stderr.write(
+          `emit-session: WARN token rollup matched ${rollup.matched_records} subagents.jsonl record(s) ` +
+            `for ${ownUuid}, none token-bearing; total_tokens omitted\n`
+        );
+      }
+    } else if (rollup !== null) {
+      let warning = `token rollup found no subagents.jsonl records for ${ownUuid}`;
+      switch (rollup.match_status) {
+        case 'ledger-absent':
+          warning += ' (ledger absent)';
+          break;
+        case 'ledger-empty':
+          warning += ' (ledger holds no readable records)';
+          break;
+        case 'unmatched':
+          warning = `token rollup found ${rollup.ledger_records} subagents.jsonl record(s) present, ` +
+            `none with parent_session_id=${ownUuid} — not attributable via this UUID, not zero cost`;
+          break;
+        case 'invalid-key':
+          warning = `token rollup rejected invalid parent_session_id=${ownUuid}`;
+          break;
+        default:
+          // Unknown or missing diagnostics retain the generic omission warning.
+          break;
+      }
+      process.stderr.write(`emit-session: WARN ${warning}; omitting token fields\n`);
+    }
+  }
+
   let validated;
   try {
     validated = validateSession(repaired);

package/scripts/export-hw-learnings.mjs

@@ -14,8 +14,9 @@
  * research/hardware-patterns.md`), via the same `vault-integration.vault-dir`
  * resolution `scripts/archive-closed-prds.mjs` uses (findProjectRoot →
  * CLAUDE.md/AGENTS.md → parseSessionConfig; host-resolved: SO_VAULT_DIR env >
- * owner.yaml paths.vault-dir > committed default). Pass `--output <path>` to
- * override.
+ * owner.yaml vault-dirs: cwd match > owner.yaml paths.vault-dir > committed
+ * default, see `resolveVaultDir` in scripts/lib/config.mjs). Pass `--output <path>`
+ * to override.
  *
  * Idempotent: running without new data rewrites the same file byte-for-byte
  * modulo the generated-at line.
@@ -58,6 +59,7 @@ import {
   rewriteLearnings,
   CURRENT_ANONYMIZATION_VERSION,
 } from './lib/learnings.mjs';
+import { withLearningsLock } from './lib/learnings/io.mjs';
 import { findProjectRoot, resolveInstructionFile, expandTilde } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
 import { createSecretValueMasker } from './lib/secret-masker.mjs';
@@ -74,7 +76,8 @@ const DEFAULT_VAULT_SUBPATH = path.join('01-projects', 'session-orchestrator', '
  * explicitly. Mirrors the vault-dir resolution `scripts/archive-closed-prds.mjs`
  * uses: findProjectRoot → CLAUDE.md/AGENTS.md → parseSessionConfig →
  * vault-integration.vault-dir (host-resolved: SO_VAULT_DIR env > owner.yaml
- * paths.vault-dir > committed default).
+ * vault-dirs: cwd match > owner.yaml paths.vault-dir > committed default, see
+ * `resolveVaultDir` in scripts/lib/config.mjs).
  *
  * @param {object} [opts]
  * @param {string} [opts.repoRoot] — override for findProjectRoot() (tests).
@@ -634,6 +637,22 @@ function parseArgs(argv) {
  * @returns {Promise<{promoted: number, skipped: number, flags: string[]}>}
  */
 export async function promoteHwLearnings(opts) {
+  // The read → rewrite below runs under the store lock (#1447 point 8): an
+  // append landing between them would vanish in the rename. A dry run writes
+  // nothing and takes no lock. A lock not acquired throws LearningsLockError
+  // (nothing written), which the CLI reports as `export failed: …`, exit 1.
+  if (opts.dryRun) return promoteHwLearningsUnlocked(opts);
+  return withLearningsLock(opts.input, () => promoteHwLearningsUnlocked(opts));
+}
+
+/**
+ * Body of {@link promoteHwLearnings}; the caller holds the store lock or runs
+ * a dry run.
+ *
+ * @param {Parameters<typeof promoteHwLearnings>[0]} opts
+ * @returns {Promise<{promoted: number, skipped: number, flags: string[]}>}
+ */
+async function promoteHwLearningsUnlocked(opts) {
   const repoRoot = opts.repoRoot;
   const { entries, malformed } = await readLearnings(opts.input);