session-orchestrator 3.23.0 → 4.0.0

package/scripts/lib/quality-gate.mjs

@@ -67,7 +67,7 @@ import { fileURLToPath } from 'node:url';
 import { emitEvent, sessionAttribution } from './events.mjs';
 import { admitSuiteCounts, extractTestCounts } from './gates/gate-helpers.mjs';
 import { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
-import { readLock } from './session-lock.mjs';
+import { readProcessLocalSessionIds } from './session-identity/own-session.mjs';
 
 export { redactDiagnosticsBundle } from './quality-gate/diagnostics.mjs';
 
@@ -114,30 +114,99 @@ function resolveRepoRoot(explicit) {
 }
 
 /**
- * Load default commands from Session Config via `scripts/parse-config.mjs`.
- * Returns a partial object — keys that fail to resolve are simply absent
- * (the caller falls through to DEFAULT_COMMANDS for those).
+ * Closed set of `degraded` reasons for {@link loadCommandsFromSessionConfigDetailed}.
+ *
+ * Its own enum, deliberately not shared with `ci-status-banner.mjs`'s
+ * `DEGRADED_REASONS`: the members below are exactly the three ways THIS
+ * config-read can fail, and an enum whose members are not exhaustively
+ * reachable cannot be switched on exhaustively.
+ *
+ *   - `script-missing` — `scripts/parse-config.mjs` is not on disk.
+ *   - `spawn-failed`   — the subprocess exited non-zero, timed out, or wrote
+ *                        nothing to stdout.
+ *   - `parse-error`    — stdout was not parseable JSON (or the read threw).
+ */
+export const CONFIG_READ_DEGRADED_REASONS = Object.freeze([
+  'script-missing',
+  'spawn-failed',
+  'parse-error',
+]);
+
+/**
+ * Does `repoRoot` carry a Session Config file at all?
+ *
+ * Mirrors the file-name precedence `scripts/parse-config.mjs::resolveConfigFile`
+ * uses (`SO_CONFIG_FILE` → `CLAUDE.md` → `AGENTS.md`) but NOT its upward
+ * project-root walk — see the ceiling note at the call site.
+ *
+ * @param {string} repoRoot
+ * @returns {boolean}
+ */
+function sessionConfigFileExists(repoRoot) {
+  try {
+    const soConfigFile = process.env.SO_CONFIG_FILE;
+    if (soConfigFile && existsSync(join(repoRoot, soConfigFile))) return true;
+    return existsSync(join(repoRoot, 'CLAUDE.md')) || existsSync(join(repoRoot, 'AGENTS.md'));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load default commands from Session Config via `scripts/parse-config.mjs`,
+ * distinguishing "the config declares no `*-command` keys" from "the config
+ * could not be read at all".
+ *
+ * Both cases yield `commands: {}` — that half is unchanged, and every command
+ * resolution keeps falling through to DEFAULT_COMMANDS exactly as before. What
+ * is new is the second channel: on failure the result also carries a
+ * `degraded` reason from {@link CONFIG_READ_DEGRADED_REASONS}. Without it,
+ * `checkQgCommandDrift` reported "no drift" for a config it never managed to
+ * read — a silent all-clear derived from an absent measurement (#1031's
+ * failure class, one consumer over).
+ *
+ * `degraded` is OMITTED, not set to null, on the success path, so a strict
+ * `toEqual({commands: {…}})` pin holds for every readable config.
  *
  * Never throws.
  *
  * @param {string} repoRoot
- * @returns {{lint?: string, typecheck?: string, test?: string}}
+ * @returns {{commands: {lint?: string, typecheck?: string, test?: string},
+ *            degraded?: 'script-missing'|'spawn-failed'|'parse-error'}}
  */
-export function loadCommandsFromSessionConfig(repoRoot) {
+export function loadCommandsFromSessionConfigDetailed(repoRoot) {
   try {
     const scriptPath = join(
       dirname(fileURLToPath(import.meta.url)),
       '..',
       'parse-config.mjs',
     );
-    if (!existsSync(scriptPath)) return {};
+    if (!existsSync(scriptPath)) return { commands: {}, degraded: 'script-missing' };
     const result = spawnSync('node', [scriptPath], {
       cwd: repoRoot,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 10_000,
     });
-    if (result.status !== 0 || !result.stdout) return {};
+    if (result.status !== 0 || !result.stdout) {
+      // `parse-config.mjs` exits 1 for EVERY failure, including the benign
+      // "this repo has no CLAUDE.md / AGENTS.md at all" — measured 2026-09-05
+      // in an empty tmp dir: stderr `CLAUDE.md or AGENTS.md required`, exit 1.
+      // A repo with no Session Config has no `*-command` value that could
+      // drift, so reporting that as a failed READ would fire a warning on every
+      // such repo (`.claude/rules/host-resources.md` § HR-101 — a warning class
+      // that is usually present is a broken instrument).
+      //
+      // Ceiling (BV-004): `parse-config.mjs` resolves its config via
+      // `findProjectRoot(cwd)` walking UPWARD, this check looks only at
+      // `repoRoot` itself. For a `repoRoot` nested below the project root the
+      // two disagree — and the disagreement resolves toward SILENCE (no
+      // `degraded`), i.e. the pre-#1031 behaviour, never toward a false alarm.
+      // Revisit if a caller starts passing sub-directory roots.
+      return sessionConfigFileExists(repoRoot)
+        ? { commands: {}, degraded: 'spawn-failed' }
+        : { commands: {} };
+    }
     const cfg = JSON.parse(result.stdout);
     const out = {};
     if (typeof cfg['lint-command'] === 'string' && cfg['lint-command'].trim()) {
@@ -149,12 +218,30 @@ export function loadCommandsFromSessionConfig(repoRoot) {
     if (typeof cfg['test-command'] === 'string' && cfg['test-command'].trim()) {
       out.test = cfg['test-command'];
     }
-    return out;
+    return { commands: out };
   } catch {
-    return {};
+    return { commands: {}, degraded: 'parse-error' };
   }
 }
 
+/**
+ * Load default commands from Session Config via `scripts/parse-config.mjs`.
+ * Returns a partial object — keys that fail to resolve are simply absent
+ * (the caller falls through to DEFAULT_COMMANDS for those).
+ *
+ * Thin wrapper over {@link loadCommandsFromSessionConfigDetailed}; byte-identical
+ * return value for every input, including every failure path. Callers that need
+ * to tell a failed read from an empty config use the detailed variant.
+ *
+ * Never throws.
+ *
+ * @param {string} repoRoot
+ * @returns {{lint?: string, typecheck?: string, test?: string}}
+ */
+export function loadCommandsFromSessionConfig(repoRoot) {
+  return loadCommandsFromSessionConfigDetailed(repoRoot).commands;
+}
+
 /**
  * Resolve the three gate commands. Precedence: override > session config > defaults.
  *
@@ -420,44 +507,32 @@ function listChangedFiles(repoRoot, ref) {
  * The id-space THIS process belongs to, for comparison against a repo-global
  * file that any session in the working copy may have written.
  *
- * Two sources, both read rather than invented — this deliberately adds no third
- * way of answering "who am I" (`scripts/lib/lock-reaper.mjs` takes the id from
- * its caller; `scripts/lib/peer-discovery.mjs` reads `readLock()`):
- *
- *   1. `CLAUDE_CODE_SESSION_ID` — the only PER-PROCESS source, and therefore
- *      the only one a foreign session cannot spoof by writing a file. Measured
- *      2026-08-23 inside a dispatched wave agent: present, and equal to the
- *      coordinator's `current-session.json` `session_id` (a child session
- *      inherits the parent's id, which is what makes it usable here).
- *      `scripts/lib/spiral-carryover.mjs` reads the same variable, under the
- *      same measured premise.
- *   2. `session.lock` `session_id` / `semantic_session_id` — a repo-global
- *      FALLBACK for harnesses that export no session env var. Weaker on
- *      purpose: the lock is one more shared file in the same working copy, so
- *      it can name a peer rather than us. It is used only when (1) is absent,
- *      where the alternative is no check at all.
+ * Process-local witnesses ONLY (`CLAUDE_CODE_SESSION_ID`, via
+ * {@link readProcessLocalSessionIds}) — the `session.lock` fallback this
+ * function used to carry is deliberately GONE, not merely deprioritised.
+ * `session.lock` is a repo-GLOBAL artefact any session in the working copy
+ * can hold; unioning or falling back to it made a shared resource stand in
+ * for a process-local identity, which is exactly the #1194 hazard class
+ * (`.claude/rules/host-resources.md` § HR-102 — "a better signal REPLACES a
+ * worse one, it does not merely suppress it"). Concretely for this module
+ * (#1205): without the env var, a process that is NOT the lock holder used to
+ * silently adopt the lock holder's id as its own, so a `current-session.json`
+ * written by that same holder passed the ownership check by construction.
+ * `readProcessLocalSessionIds()` (`./session-identity/own-session.mjs`) is
+ * the shared, already-hardened implementation of this exact question — see
+ * its JSDoc for the full lock/STATE.md exclusion rationale.
+ *
+ * An empty result is not a mismatch: {@link classifyCurrentSessionOwnership}
+ * treats an empty `ownIds` as `'unknown'`, never `'foreign'`, so
+ * `corrective_context` is kept — the existing fail-open contract from #1058,
+ * unchanged by this fix.
  *
- * @param {string} repoRoot
  * @returns {Set<string>} possibly empty — an empty set means "identity
  *   unresolvable", which the classifier below treats as `unknown`, never as a
  *   mismatch.
  */
-function readOwnSessionIds(repoRoot) {
-  const ids = new Set();
-  // `.trim()` first: a whitespace-only env var is truthy and would otherwise
-  // enter the set as a phantom id (`development.md` § env-var whitespace trap).
-  const fromEnv = (process.env.CLAUDE_CODE_SESSION_ID || '').trim();
-  if (fromEnv) ids.add(fromEnv);
-  if (ids.size === 0) {
-    try {
-      const lock = readLock({ repoRoot });
-      for (const key of ['session_id', 'semantic_session_id']) {
-        const value = typeof lock?.[key] === 'string' ? lock[key].trim() : '';
-        if (value) ids.add(value);
-      }
-    } catch { /* readLock never throws, but the contract is not ours to trust */ }
-  }
-  return ids;
+function readOwnSessionIds() {
+  return new Set(readProcessLocalSessionIds({ env: process.env, hookInput: null }));
 }
 
 /**
@@ -534,7 +609,8 @@ function readCorrectiveContext(repoRoot) {
     if (!existsSync(p)) return [];
     const raw = readFileSync(p, 'utf8');
     const parsed = JSON.parse(raw);
-    const { verdict, fileIds } = classifyCurrentSessionOwnership(parsed, readOwnSessionIds(repoRoot));
+    const ownIds = readOwnSessionIds();
+    const { verdict, fileIds } = classifyCurrentSessionOwnership(parsed, ownIds);
     if (verdict === 'foreign') {
       process.stderr.write(
         `⚠️  quality-gate: .orchestrator/current-session.json belongs to another session ` +
@@ -543,6 +619,19 @@ function readCorrectiveContext(repoRoot) {
       );
       return [];
     }
+    // The fail-open half of `verdict === 'unknown'`: the file DOES name an id,
+    // but this process has no process-local witness of its own (ownIds is
+    // empty — no `CLAUDE_CODE_SESSION_ID`, e.g. Codex/Cursor). Ownership is
+    // unprovable, so the content is kept per the #1058 contract — but silently
+    // is the wrong word for that: make the fail-open visible on stderr rather
+    // than indistinguishable from a verified 'own' match.
+    if (verdict === 'unknown' && fileIds.length > 0 && ownIds.size === 0) {
+      process.stderr.write(
+        '⚠ quality-gate: cannot verify ownership of .orchestrator/current-session.json ' +
+        '(no process-local session id — CLAUDE_CODE_SESSION_ID unset); keeping corrective_context ' +
+        `from session ${fileIds.join(', ')} UNVERIFIED\n`,
+      );
+    }
     const arr = Array.isArray(parsed?.corrective_context) ? parsed.corrective_context : [];
     return arr.slice(-CORRECTIVE_CONTEXT_TAIL);
   } catch {

package/scripts/lib/reconcile/emitter.mjs

@@ -172,18 +172,37 @@ const GLOB_METACHAR_RE = /[*?[\]{}()]|[!@+](?=\()/;
  * {@link UNSAFE_PATH_QUOTE_RE}). Results are deduped, order-preserving on
  * first occurrence.
  *
+ * #1153 P13: skipping used to be entirely silent, so a learning whose ONLY
+ * `file_paths` entry was unusable produced the generic "no activation axis"
+ * rejection with nothing naming WHY the axis was empty. Every skipped entry is
+ * therefore recorded into the optional `dropped` sink (value + one-word
+ * reason), which {@link formatDroppedFilePaths} renders into that rejection
+ * reason. The sink is an out-parameter rather than a changed return type so
+ * every existing caller stays byte-identical.
+ *
  * @param {string[]} filePaths
+ * @param {{value: string, reason: string}[]} [dropped] - out-param sink
  * @returns {string[]}
  */
-function globsFromFilePaths(filePaths) {
+function globsFromFilePaths(filePaths, dropped) {
   const out = [];
   const seen = new Set();
   for (const raw of filePaths) {
     if (typeof raw !== 'string' || raw === '') continue;
-    if (GLOB_METACHAR_RE.test(raw)) continue;
+    if (GLOB_METACHAR_RE.test(raw)) {
+      dropped?.push({ value: raw, reason: 'glob-metachar' });
+      continue;
+    }
     // #1015: frontmatter-structure guard. Skipping (never escaping) keeps this
     // idempotent and non-overlapping with the renderer's sanitiser.
-    if (CONTROL_CHARS_TEST_RE.test(raw) || UNSAFE_PATH_QUOTE_RE.test(raw)) continue;
+    if (CONTROL_CHARS_TEST_RE.test(raw)) {
+      dropped?.push({ value: raw, reason: 'control-char' });
+      continue;
+    }
+    if (UNSAFE_PATH_QUOTE_RE.test(raw)) {
+      dropped?.push({ value: raw, reason: 'quote' });
+      continue;
+    }
     const normalized = raw.replace(/\\/g, '/');
     const dir = dirname(normalized);
     const pattern = dir === '.' ? normalized : `${dir}/**`;
@@ -195,6 +214,42 @@ function globsFromFilePaths(filePaths) {
   return out;
 }
 
+/** Max chars of a single dropped `file_paths` value in a rejection reason. */
+const DROPPED_VALUE_MAX = 60;
+
+/**
+ * Render the `dropped` sink of {@link globsFromFilePaths} into a suffix for the
+ * never-always-on rejection reason (#1153 P13).
+ *
+ * The reason string is OPERATOR-VISIBLE (engine.mjs forwards it verbatim into
+ * `reason: emit/render error: …` and from there into the candidates ledger), so
+ * a hostile `file_paths` entry must not be able to inject newlines or ANSI into
+ * it. Each value is therefore `JSON.stringify`-escaped — which turns every
+ * control char into a `\uXXXX` literal — and then hard-truncated to
+ * {@link DROPPED_VALUE_MAX} chars, with any trailing partial backslash escape
+ * removed so the cut cannot end mid-sequence.
+ *
+ * @param {{value: string, reason: string}[]} dropped
+ * @returns {string} `''` when nothing was dropped, else a ` — dropped …` suffix
+ */
+function formatDroppedFilePaths(dropped) {
+  if (!Array.isArray(dropped) || dropped.length === 0) return '';
+  const rendered = dropped.map(({ value, reason }) => {
+    const escaped = JSON.stringify(String(value));
+    const clipped =
+      escaped.length <= DROPPED_VALUE_MAX
+        ? escaped
+        // A `\uXXXX` escape is 6 chars, so the cut can land at FIVE distinct
+        // depths inside one — and `/\\+$/` only ever caught the shallowest
+        // (`\`). Measured at DROPPED_VALUE_MAX=60 with a NUL at offsets 53..56:
+        // the old form left `\u000`, `\u00`, `\u0` and `\u` standing. Strip the
+        // backslash together with up to three hex digits of a partial `u`-escape.
+        : `${escaped.slice(0, DROPPED_VALUE_MAX - 1).replace(/\\(u[0-9a-fA-F]{0,3})?$/, '')}…`;
+    return `${clipped} (${reason})`;
+  });
+  return ` — dropped file_paths: ${dropped.length} (${rendered.join(', ')})`;
+}
+
 /**
  * Build a single-line, frontmatter-safe description from a learning.
  *
@@ -320,7 +375,8 @@ export function toActivationMetadata(learning, { ruleExpiryDays, now, minRuleDay
   }
 
   const filePaths = Array.isArray(learning.file_paths) ? learning.file_paths : [];
-  const globs = globsFromFilePaths(filePaths);
+  const droppedFilePaths = [];
+  const globs = globsFromFilePaths(filePaths, droppedFilePaths);
 
   // #1015: `host_class` is copied straight into an UNQUOTED `host-class:`
   // frontmatter line by the renderer, so its SHAPE is load-bearing. Reject a
@@ -358,16 +414,22 @@ export function toActivationMetadata(learning, { ruleExpiryDays, now, minRuleDay
   // The brandmauer: an auto-generated rule must carry ≥1 activation axis. If we
   // could derive neither a glob nor a host-class, refuse — never emit always-on.
   if (globs.length === 0 && hostClass === undefined) {
+    // #1153 P13: name the entries that were silently skipped on the way here —
+    // otherwise "no activation axis" is indistinguishable from "no file_paths
+    // at all", and the operator has no way to see that a malformed record (not
+    // an empty one) caused the rejection.
+    const droppedSuffix = formatDroppedFilePaths(droppedFilePaths);
     if (hostClassDroppedByType) {
       throw new Error(
         `emitter: host_class ${JSON.stringify(learning.host_class)} is present and well-formed, but type ` +
           `${JSON.stringify(learning.type)} is not host-specific (#1090 — host-class is only copied through for ` +
           `${[...HOST_SPECIFIC_TYPES].join(', ')}) — refusing to emit always-on auto-generated rule ` +
-          '(never-always-on invariant); no other activation axis (globs) is available either.',
+          `(never-always-on invariant); no other activation axis (globs) is available either.${droppedSuffix}`,
       );
     }
     throw new Error(
-      'emitter: no activation axis (globs/host-class) — refusing to emit always-on auto-generated rule (never-always-on invariant)',
+      'emitter: no activation axis (globs/host-class) — refusing to emit always-on auto-generated rule ' +
+        `(never-always-on invariant)${droppedSuffix}`,
     );
   }
 

package/scripts/lib/reconcile/engine.mjs

@@ -33,10 +33,16 @@
  * the engine performs is into the reconcile-candidates sidecar (via
  * idempotency.mjs), and even that is skipped under `dryRun`.
  *
- * ── never-throws contract ────────────────────────────────────────────────────
- * `runReconcile` NEVER throws to its caller. A per-learning emit/render failure
- * degrades to a recorded rejection (never a crash); any unexpected top-level
- * error returns a zeroed result with an `error` field.
+ * ── never-throws contract (PIPELINE errors only) ─────────────────────────────
+ * Once the pipeline is running, `runReconcile` NEVER throws to its caller: a
+ * per-learning emit/render failure degrades to a recorded rejection (never a
+ * crash), and any unexpected top-level pipeline error returns a zeroed result
+ * with an `error` field. The ONE exception is a caller-INPUT validation error
+ * at the very top of `runReconcile` — an explicitly-passed `trigger` outside
+ * `KNOWN_TRIGGERS` (issue #1201 Part A) THROWS synchronously before the
+ * pipeline ever starts, the same class of failure as passing a malformed
+ * `params` object to any other function in this codebase; see
+ * `assertKnownTrigger` below.
  *
  * Plain Node ESM, no external deps — Node 20+ stdlib + the four siblings only.
  *
@@ -154,8 +160,10 @@ function zeroedResult(error) {
 /**
  * Default learnings loader — read + parse `<repoRoot>/.orchestrator/metrics/learnings.jsonl`
  * line-by-line, migrate/normalize records through the learnings schema SSOT,
- * and skip blank/malformed lines. A missing file yields `[]`. Never throws (a
- * read error degrades to `[]`).
+ * and skip blank/malformed lines. A missing file (ENOENT) yields `[]`
+ * silently; an unreadable one (EACCES/EISDIR/…) yields `[]` with a stderr
+ * WARN (#1210 — ENOENT and other read failures are different facts, same
+ * split as `sessions-canonical.mjs` `readCanonicalSessions`).
  *
  * @param {string|undefined} repoRoot
  * @returns {Array<Record<string, unknown>>}
@@ -169,8 +177,15 @@ function defaultLoadLearnings(repoRoot) {
   let raw;
   try {
     raw = readFileSync(absPath, 'utf8');
-  } catch {
-    return []; // ENOENT or any read error → empty corpus.
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      process.stderr.write(
+        `⚠ defaultLoadLearnings: cannot read ${absPath} ` +
+          `(${err?.code ?? '?'}: ${err?.message ?? String(err)}) — ` +
+          'treating as EMPTY, counts below are floors\n',
+      );
+    }
+    return [];
   }
 
   /** @type {Array<Record<string, unknown>>} */
@@ -463,7 +478,7 @@ function defaultReadMaterializedProvenance(repoRoot) {
  * @param {boolean} [opts.dryRun]         - when true, compute proposals but SKIP the merge entirely.
  * @returns {Promise<ReconcileResult>}
  */
-export async function runReconcile(
+async function runReconcileInner(
   {
     repoRoot,
     ruleExpiryDays,
@@ -780,3 +795,228 @@ export async function runReconcile(
     return zeroedResult(msg);
   }
 }
+
+/**
+ * Ledger name of the reconcile run event (issue #1192). Catalogued in
+ * `docs/events-schema.md`; `events-schema.mjs` needs no registration — it
+ * validates the NAME shape only, and this name already satisfies it.
+ */
+export const RECONCILE_EVENT = 'orchestrator.reconcile.completed';
+
+/**
+ * Closed enum of `trigger` values a caller may explicitly pass to
+ * {@link runReconcile} (issue #1201 Part A / Discovery D8). Two of the three
+ * real call sites pinned `trigger` by PROSE inside a `.md` skill file —
+ * `skill` (`skills/reconcile/SKILL.md`) and `session-end`
+ * (`skills/session-end/phase-3-6-tail.md`) — where nothing enforced the
+ * string ever matched this list; only `phase-skip`
+ * (`scripts/lib/session-end/phase-skip.mjs`) pinned it in code. The two `.md`
+ * callers are migrated onto {@link runReconcileFromSkill} /
+ * {@link runReconcileAtSessionEnd} in this same change, so "prose sets the
+ * trigger" stops being possible for them at all.
+ */
+export const KNOWN_TRIGGERS = Object.freeze(['skill', 'session-end', 'phase-skip']);
+
+/**
+ * Reject an explicitly-passed `trigger` that is not in {@link KNOWN_TRIGGERS}
+ * — including the literal `'unknown'`, which is a DEFAULT this module mints
+ * for an ABSENT trigger, never a value a caller should pass on purpose. An
+ * absent trigger (`undefined`) is deliberately let through unchanged: it is
+ * legacy behaviour for a caller that has not yet been migrated onto a pinned
+ * wrapper, and `buildReconcilePayload` already defaults it to `'unknown'` so
+ * the per-trigger denominator in the ledger stays honest about which runs are
+ * unattributed rather than silently breaking them.
+ *
+ * BV-004 revisit trigger: `scripts/lib/session-end/phase-skip.mjs` is the one
+ * remaining caller passing `trigger: 'phase-skip'` as a hand-written literal
+ * rather than through {@link runReconcileFromPhaseSkip} (out of this task's
+ * file scope) — once every caller is migrated onto a pinned wrapper, flip the
+ * absent-trigger default below from "let it run" to a throw, closing the last
+ * legacy path.
+ *
+ * @param {unknown} trigger
+ * @throws {Error} when `trigger` is defined but not in `KNOWN_TRIGGERS`.
+ * @returns {void}
+ */
+export function assertKnownTrigger(trigger) {
+  if (trigger === undefined) return;
+  if (!KNOWN_TRIGGERS.includes(trigger)) {
+    throw new Error(
+      `runReconcile: invalid trigger ${JSON.stringify(trigger)} — must be one of: ` +
+        `${KNOWN_TRIGGERS.join(', ')} (or omitted entirely, for a not-yet-migrated caller).`,
+    );
+  }
+}
+
+/** Clamp for the `reason` string on the abort path — a message can be long. */
+const REASON_MAX_CHARS = 300;
+
+/** The closed target enum `resolveEffectiveTargets` recognises. */
+const KNOWN_TARGETS = ['repo-local', 'baseline'];
+
+/**
+ * Build the `orchestrator.reconcile.completed` payload from a finished run.
+ *
+ * Counter fields are written INCLUDING `0`: each was MEASURED over the whole
+ * run, so a written zero is the payload (same contract as the vault-mirror run
+ * event). The two absence-preserving exceptions are `store_records_dropped`
+ * (absent ⇒ the candidate store was never inspected — dryRun, empty
+ * short-circuit, error path) and `targets` (absent ⇒ the caller asserted no
+ * target list). `aborted`/`reason` appear only when the never-throws guard
+ * fired; their absence means "ran to the end", never "unknown".
+ *
+ * @param {ReconcileResult} result
+ * @param {{ trigger?: string, targets?: string[], dryRun?: boolean, durationMs: number }} ctx
+ * @returns {Record<string, unknown>}
+ */
+function buildReconcilePayload(result, ctx) {
+  const summary = (result && result.summary) || {};
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    trigger: typeof ctx.trigger === 'string' && ctx.trigger.trim() !== '' ? ctx.trigger : 'unknown',
+    dry_run: ctx.dryRun === true,
+    learnings_total: summary.totalLearnings ?? 0,
+    eligible: summary.eligible ?? 0,
+    proposals: summary.proposed ?? 0,
+    rejected: summary.rejected ?? 0,
+    capped: summary.capped ?? 0,
+    already_materialized: summary.alreadyMaterialized ?? 0,
+    written: summary.written === true,
+    duration_ms: ctx.durationMs,
+  };
+  // `targets` originates in operator-authored Session Config (`reconcile.targets`)
+  // and is unbounded there. Allowlisted to the CLOSED enum `resolveEffectiveTargets`
+  // recognises before it enters the ledger and the optional Clank webhook (Q2-F4):
+  // anything else is not a target this engine can act on, so recording it would
+  // be a verbatim echo of untrusted text, never a measurement. Omitted when empty.
+  const targets = Array.isArray(ctx.targets)
+    ? [...new Set(ctx.targets.filter((t) => KNOWN_TARGETS.includes(t)))]
+    : [];
+  if (targets.length > 0) payload.targets = targets;
+  if (typeof summary.skipped === 'number') payload.store_records_dropped = summary.skipped;
+  if (typeof result?.error === 'string' && result.error !== '') {
+    payload.aborted = 'engine-error';
+    payload.reason = result.error.slice(0, REASON_MAX_CHARS);
+  }
+  return payload;
+}
+
+/**
+ * Record one reconcile run in the repo's event ledger — best-effort.
+ *
+ * Refuses the ambient `SO_PROJECT_DIR` destination when no `repoRoot` was
+ * given: most engine tests call `runReconcile` without one, and a fallback
+ * would append synthetic records to the operator's REAL fleet ledger on every
+ * `npm test` (#1119, `scripts/lib/express-path.mjs`). Diagnostics on stderr.
+ *
+ * @param {ReconcileResult} result
+ * @param {{ repoRoot?: string, trigger?: string, targets?: string[], dryRun?: boolean, durationMs: number }} ctx
+ */
+async function emitReconcileCompleted(result, ctx) {
+  const { repoRoot } = ctx;
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') {
+    process.stderr.write(
+      `reconcile: skipped ${RECONCILE_EVENT} — no repoRoot given; ` +
+        'refusing the ambient SO_PROJECT_DIR destination (#1119).\n',
+    );
+    return;
+  }
+  const { emitEvent } = await import('../events.mjs');
+  await emitEvent(RECONCILE_EVENT, buildReconcilePayload(result, ctx), { repoRoot });
+}
+
+/**
+ * Public boundary: run the reconciliation pipeline and record the run.
+ *
+ * A thin WRAPPER, deliberately: the pipeline has three return points (empty
+ * short-circuit, normal tail, never-throws catch), and an inline emit would
+ * miss two of them — including the empty corpus and the error path, the two
+ * runs an operator most needs recorded (`.claude/rules/host-resources.md`
+ * § HR-105). Same shape as `runNarrativeMirror` + `mirrorNarrative` in
+ * `scripts/lib/vault-status/narrative-mirror.mjs`.
+ *
+ * The emit is wrapped in try/catch because `emitEvent` THROWS
+ * `EventValidationError` on an invalid record — without the catch, telemetry
+ * would break this function's never-throws contract. The pipeline's result is
+ * returned UNTOUCHED whether or not the ledger accepted the record.
+ *
+ * @param {Object} [params] - see {@link runReconcileInner}, plus:
+ * @param {'skill'|'session-end'|'phase-skip'} [params.trigger] - which caller
+ *        invoked this run; recorded ALWAYS (default `'unknown'` when omitted) so
+ *        the per-trigger denominator is complete. Not read by the pipeline.
+ *        VALIDATED against {@link KNOWN_TRIGGERS} via {@link assertKnownTrigger}
+ *        when explicitly passed — an unknown string, including the literal
+ *        `'unknown'`, THROWS synchronously; an absent trigger is still let
+ *        through unchanged (issue #1201 Part A — see `assertKnownTrigger`'s
+ *        BV-004 revisit-trigger note for why the absent case is not also a
+ *        throw yet). Prefer {@link runReconcileFromSkill},
+ *        {@link runReconcileAtSessionEnd}, or {@link runReconcileFromPhaseSkip}
+ *        over passing `trigger` here directly.
+ * @param {string[]} [params.targets] - the caller's effective target list
+ *        (`resolveEffectiveTargets`); recorded when non-empty, omitted otherwise.
+ *        Not read by the pipeline.
+ * @param {Object} [opts] - see {@link runReconcileInner}.
+ * @returns {Promise<ReconcileResult>}
+ */
+export async function runReconcile(params = {}, opts = {}) {
+  assertKnownTrigger(params.trigger);
+  const t0 = Date.now();
+  const result = await runReconcileInner(params, opts);
+  try {
+    await emitReconcileCompleted(result, {
+      repoRoot: params.repoRoot,
+      trigger: params.trigger,
+      targets: params.targets,
+      dryRun: params.dryRun === true || opts.dryRun === true,
+      durationMs: Date.now() - t0,
+    });
+  } catch {
+    // Best-effort telemetry — never the reason a reconcile run fails.
+  }
+  return result;
+}
+
+/**
+ * Pin `trigger: 'skill'` in code for the `/reconcile` skill (Phase 2.3,
+ * `skills/reconcile/SKILL.md`) — the skill's own `.md` prose no longer sets
+ * the trigger string itself (issue #1201 Part A). Any `trigger` the caller
+ * passes in `params` is OVERWRITTEN; every other field forwards unchanged.
+ *
+ * @param {Object} [params] - see {@link runReconcile} `params`.
+ * @param {Object} [opts] - see {@link runReconcile} `opts` (DI seams).
+ * @returns {Promise<ReconcileResult>}
+ */
+export async function runReconcileFromSkill(params = {}, opts = {}) {
+  return runReconcile({ ...params, trigger: 'skill' }, opts);
+}
+
+/**
+ * Pin `trigger: 'session-end'` in code for session-end Phase 3.6.8
+ * (`skills/session-end/phase-3-6-tail.md`) — see
+ * {@link runReconcileFromSkill} for the rationale and contract.
+ *
+ * @param {Object} [params] - see {@link runReconcile} `params`.
+ * @param {Object} [opts] - see {@link runReconcile} `opts` (DI seams).
+ * @returns {Promise<ReconcileResult>}
+ */
+export async function runReconcileAtSessionEnd(params = {}, opts = {}) {
+  return runReconcile({ ...params, trigger: 'session-end' }, opts);
+}
+
+/**
+ * Pin `trigger: 'phase-skip'` in code for the session-end skip-plan
+ * aggregator (`scripts/lib/session-end/phase-skip.mjs`, the highest-volume
+ * probe-only caller) — see {@link runReconcileFromSkill} for the rationale
+ * and contract. NOT YET wired into `phase-skip.mjs` itself, which is out of
+ * this task's file scope and still passes `trigger: 'phase-skip'` as a
+ * hand-written literal directly to `runReconcile`; exported here so that
+ * migration is a one-line import swap (see `assertKnownTrigger`'s BV-004
+ * revisit-trigger note).
+ *
+ * @param {Object} [params] - see {@link runReconcile} `params`.
+ * @param {Object} [opts] - see {@link runReconcile} `opts` (DI seams).
+ * @returns {Promise<ReconcileResult>}
+ */
+export async function runReconcileFromPhaseSkip(params = {}, opts = {}) {
+  return runReconcile({ ...params, trigger: 'phase-skip' }, opts);
+}