session-orchestrator 5.3.0 → 5.5.0

package/scripts/cursor-install.mjs

@@ -15,11 +15,22 @@
  *   1 — source rules not found, or TARGET is not an existing directory
  */
 
-import { existsSync, mkdirSync, readdirSync, symlinkSync, statSync, lstatSync, writeFileSync } from 'node:fs';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readlinkSync,
+  symlinkSync,
+  statSync,
+  lstatSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
 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,14 +73,12 @@ 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)) {
-    process.stdout.write(`  SKIP: ${label} (symlink exists)\n`);
+    // existsSync follows the link: false means it points at nothing.
+    const state = existsSync(dest) ? 'symlink exists' : 'dangling symlink — not replacing';
+    process.stdout.write(`  SKIP: ${label} (${state})\n`);
     return 'skip';
   }
   if (existsSync(dest)) {
@@ -122,6 +131,38 @@ if (_isDir(SOURCE_SKILLS_DIR)) {
   }
 }
 
+/**
+ * Remove the links an earlier install left for a wrapper this plugin no longer
+ * ships (#1501 item 6: 05c0264f dropped `commands/navigator.md` and
+ * `skills/navigator`, and every installed project kept a dead link). An entry is
+ * removed only when it is a symlink, dangles, AND resolves inside this plugin's
+ * `.cursor/<kind>/` — so it is provably ours. Regular files and live links are
+ * the project's own; a dangling link into another root is not ours to delete
+ * and gets a WARN — unless this plugin ships that name, where linkPath() has
+ * already reported it as dangling.
+ * @param {'rules'|'commands'|'skills'} kind
+ */
+function pruneDeadLinks(kind) {
+  const sourceDir = path.join(SO_ROOT, '.cursor', kind);
+  const targetDir = path.join(TARGET, '.cursor', kind);
+  if (!_isDir(targetDir)) return;
+  for (const name of readdirSync(targetDir)) {
+    const dest = path.join(targetDir, name);
+    if (!_isSymlink(dest) || existsSync(dest)) continue;
+    const pointsTo = path.resolve(path.dirname(dest), readlinkSync(dest));
+    const rel = path.relative(sourceDir, pointsTo);
+    const ours = rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+    if (ours) {
+      unlinkSync(dest);
+      process.stdout.write(`  PRUNE: ${kind}/${name} (dangling link into ${sourceDir})\n`);
+    } else if (!existsSync(path.join(sourceDir, name))) {
+      process.stdout.write(`  WARN: ${kind}/${name} (dangling link outside this plugin, left alone: ${pointsTo})\n`);
+    }
+  }
+}
+
+for (const kind of ['rules', 'commands', 'skills']) pruneDeadLinks(kind);
+
 function renderHooksJson(soRoot) {
   const runNode = shQuote(path.join(soRoot, 'hooks', 'run-node.sh'));
   const bridge = shQuote(path.join(soRoot, 'scripts', 'lib', 'cursor-hook-bridge.mjs'));

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,124 @@ 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 cost candidate
+  // (unknown model, no model, no tokens, a started agent without a transcript,
+  // or a v1 agent — the complete list is the `session-token-rollup.mjs` module
+  // doc, #1498), 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,7 +59,8 @@ import {
   rewriteLearnings,
   CURRENT_ANONYMIZATION_VERSION,
 } from './lib/learnings.mjs';
-import { findProjectRoot, resolveInstructionFile, expandTilde } from './lib/common.mjs';
+import { withLearningsLock } from './lib/learnings/io.mjs';
+import { findProjectRoot, resolveInstructionFile, expandTilde, redactHomeDir } from './lib/common.mjs';
 import { parseSessionConfig } from './lib/config.mjs';
 import { createSecretValueMasker } from './lib/secret-masker.mjs';
 import { stableHostname, readHostAliases } from './lib/host-identity.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).
@@ -82,21 +85,28 @@ const DEFAULT_VAULT_SUBPATH = path.join('01-projects', 'session-orchestrator', '
  *   — forwarded to parseSessionConfig (tests pass `{ env: {}, ownerConfig: undefined }`
  *   for hermetic, owner.yaml-free resolution — issue #653 bleed guard).
  * @returns {string|null} the resolved output path, or null when vault-dir is
- *   unconfigured/unresolvable.
+ *   unconfigured/unresolvable or vault-integration is not enabled.
  */
 export function resolveDefaultOutput({ repoRoot, hostPaths } = {}) {
   const root = repoRoot ?? findProjectRoot();
   const instr = resolveInstructionFile(root);
   if (!instr) return null;
 
-  let vaultDir;
+  let vi;
   try {
     const content = readFileSync(instr.path, 'utf8');
     const config = parseSessionConfig(content, hostPaths ? { hostPaths } : undefined);
-    vaultDir = config?.['vault-integration']?.['vault-dir'];
+    vi = config?.['vault-integration'];
   } catch {
     return null;
   }
+  // #1506.4a: this default target IS the vault, so it obeys the off switch the
+  // other vault writers obey (vault-backfill, board-writer, narrative-mirror:
+  // `enabled !== true` → no vault write), already host-lowered by
+  // parseSessionConfig (env SO_VAULT_INTEGRATION > owner.yaml > committed). An
+  // explicit `--output` is the caller's own path and is not gated.
+  if (vi?.enabled !== true) return null;
+  const vaultDir = vi['vault-dir'];
   if (!vaultDir || typeof vaultDir !== 'string' || vaultDir.trim() === '') return null;
 
   // Expand a `~`-prefixed vault-dir (e.g. the committed Session Config default
@@ -601,7 +611,8 @@ function parseArgs(argv) {
     if (!resolved) {
       process.stderr.write(
         'export-hw-learnings: could not resolve vault-integration.vault-dir for the default ' +
-        '--output path (no CLAUDE.md/AGENTS.md found, or vault-dir is unset). ' +
+        '--output path (no CLAUDE.md/AGENTS.md found, vault-integration.enabled is not true, ' +
+        'or vault-dir is unset). ' +
         'Pass --output <path> explicitly.\n'
       );
       process.exit(1);
@@ -634,6 +645,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);
 
@@ -642,7 +669,9 @@ export async function promoteHwLearnings(opts) {
 
   const flags = [];
   if (malformed.length > 0) {
-    flags.push(`${malformed.length} malformed line(s) in learnings.jsonl were skipped`);
+    // Not promoted, and kept verbatim by the rewrite below (rewriteLearnings
+    // re-reads them under the lock — #1489); a WARN, not a loss.
+    flags.push(`${malformed.length} malformed line(s) in learnings.jsonl were not read (kept verbatim)`);
   }
 
   if (hwPrivate.length === 0) {
@@ -744,7 +773,8 @@ if (isMain) {
   };
 
   run().catch((err) => {
-    process.stderr.write(`export failed: ${err.message}\n`);
+    // The message can carry absolute store/output paths — never print the home dir.
+    process.stderr.write(`export failed: ${redactHomeDir(String(err?.message ?? err))}\n`);
     process.exit(1);
   });
 }