session-orchestrator 3.22.0 → 3.24.0

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.
  *
@@ -70,6 +76,16 @@
  *        `capped` is a diagnostic sub-count that lets a report distinguish
  *        "genuinely ineligible" rejections from "eligible but cut by the volume
  *        brake" ones at a glance.
+ * @property {number} alreadyMaterialized - count of eligible learnings that were
+ *        NOT proposed this run because they are already terminal — either the
+ *        idempotency sidecar already carries a `processed_at` stamp for their
+ *        `learning_key` (`isProcessed`), or a `.claude/rules/*.md` file already
+ *        carries a matching `learning-key`/`learning-id` provenance marker
+ *        (issue #484: 9 of 10 proposals in one run were exactly this). Runs
+ *        BEFORE the `maxProposalsPerRun` volume brake so an already-materialized
+ *        learning never consumes a new learning's quota. Same accounting pattern
+ *        as `capped`: each one is ALSO counted inside `rejected`, and
+ *        `totalLearnings === proposed + rejected` still holds unchanged.
  * @property {boolean} written
  * @property {number} [skipped] - how many persisted sidecar lines the store's
  *        read-side shape guard rejected and this run therefore DROPPED from disk
@@ -88,9 +104,10 @@
  * @property {string} [error]  - present only when the never-throws top-level guard fired.
  */
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
 
+import { expandTilde } from '../common.mjs';
 import { learningKeyOf } from '../learnings/kebab.mjs';
 import { migrateLegacyLearning, normalizeLearning } from '../learnings/schema.mjs';
 import { filterEligible } from './eligibility.mjs';
@@ -99,7 +116,9 @@ import { renderRule } from './renderer.mjs';
 import {
   DEFAULT_STORE_PATH,
   buildCandidate,
+  isProcessed,
   makeCandidateId,
+  loadCandidates as realLoadCandidates,
   mergeCandidates as realMergeCandidates,
 } from './idempotency.mjs';
 
@@ -130,6 +149,7 @@ function zeroedResult(error) {
       proposed: 0,
       rejected: 0,
       capped: 0,
+      alreadyMaterialized: 0,
       written: false,
     },
   };
@@ -238,6 +258,172 @@ function warnDroppedStoreRecords(skipped) {
   }
 }
 
+/**
+ * Session Config placeholder convention: a path key whose committed value is a
+ * marker that MUST be overridden host-locally (this repo ships
+ * `plan-baseline-path: OVERRIDE-IN-owner.yaml` in CLAUDE.md — or AGENTS.md on
+ * Codex CLI — § Session Config).
+ * Treating the marker as a real path would create `./OVERRIDE-IN-owner.yaml/`.
+ */
+const PLACEHOLDER_PATH_RE = /^OVERRIDE-IN-/;
+
+/**
+ * Report that the `baseline` write-target was dropped for this run.
+ *
+ * stderr, never stdout — `scripts/lib/config.mjs` consumers parse stdout as JSON.
+ * Same posture as {@link warnDroppedStoreRecords}: an attributable drop must be
+ * VISIBLE, and a diagnostic must never become the failure it reports on.
+ *
+ * @param {string} reason
+ */
+function warnBaselineTargetDropped(reason) {
+  try {
+    console.warn(
+      `⚠️  reconcile: target "baseline" DROPPED for this run — ${reason}. ` +
+        `Resolution order is SO_BASELINE_PATH env > owner.yaml paths.baseline-path > ` +
+        `committed plan-baseline-path. No baseline proposal is surfaced in the approval ` +
+        `AUQ and nothing is written outside this repo; every other target is unaffected.`,
+    );
+  } catch {
+    // A diagnostic must never become the failure it reports on.
+  }
+}
+
+/**
+ * Decide which reconcile targets can ACTUALLY be written this run (issue #1099).
+ *
+ * Two of the three no-op checks live here, upstream of both the approval AUQ and
+ * the writer, because the important half is not the refused write — it is that
+ * **the operator must never be asked to approve a write to a destination that
+ * cannot exist.** A `baseline` target whose root is unresolvable, is still the
+ * committed placeholder, or is not absolute is therefore dropped from the
+ * effective list BEFORE proposals are surfaced. The third check (the root does
+ * not exist on disk) belongs to `writer.mjs`, the only layer holding the
+ * filesystem at write time.
+ *
+ * Pure and never-throws: it resolves nothing from disk and reads no env — the
+ * caller passes the already-resolved `baselineRoot` (`config['plan-baseline-path']`,
+ * which `scripts/lib/config.mjs` has already run through the full 3-tier chain).
+ *
+ * @param {{targets?: unknown, baselineRoot?: unknown}} [opts]
+ * @returns {{targets: string[], baselineRoot: string|null, dropped: string[], reason: string|null}}
+ *   `targets` — the effective list; `baselineRoot` — the ~-expanded root, or null
+ *   when `baseline` is not in play; `dropped`/`reason` — the audit trail.
+ */
+export function resolveEffectiveTargets({ targets, baselineRoot } = {}) {
+  const declared = Array.isArray(targets) ? targets.filter((t) => typeof t === 'string' && t.length > 0) : [];
+  const list = [...new Set(declared.length > 0 ? declared : ['repo-local'])];
+
+  if (!list.includes('baseline')) {
+    return { targets: list, baselineRoot: null, dropped: [], reason: null };
+  }
+
+  const raw = typeof baselineRoot === 'string' ? baselineRoot.trim() : '';
+  const expanded = raw === '' ? '' : expandTilde(raw);
+
+  let reason = null;
+  if (raw === '') {
+    reason = 'no baseline path is configured on any tier';
+  } else if (PLACEHOLDER_PATH_RE.test(raw)) {
+    reason = `the committed placeholder "${raw}" was never overridden host-locally`;
+  } else if (!isAbsolute(expanded)) {
+    reason = `"${raw}" is not an absolute path after ~-expansion`;
+  }
+
+  if (reason === null) {
+    return { targets: list, baselineRoot: expanded, dropped: [], reason: null };
+  }
+
+  warnBaselineTargetDropped(reason);
+  return {
+    targets: list.filter((t) => t !== 'baseline'),
+    baselineRoot: null,
+    dropped: ['baseline'],
+    reason,
+  };
+}
+
+/**
+ * Default sidecar-candidate loader for the issue #484 idempotency dedupe
+ * check (below, step 3a). Deliberately gated on `repoRoot` being a
+ * caller-supplied, non-empty string — UNLIKE `defaultLoadLearnings` and
+ * `realMergeCandidates`, this does NOT fall back to `process.cwd()` when
+ * `repoRoot` is absent. Every existing engine test exercises this module via
+ * `opts.learnings` with no `repoRoot`, precisely to avoid touching this repo's
+ * OWN `.orchestrator/runtime/reconcile-candidates.jsonl`; a cwd fallback here
+ * would silently read it. The disk-touching default is reserved for callers
+ * that always pass an explicit `repoRoot` (the `/reconcile` skill resolves it
+ * via `git rev-parse --show-toplevel`).
+ * @param {string|undefined} repoRoot
+ * @returns {{ records: import('./idempotency.mjs').ReconcileCandidate[] }}
+ */
+function defaultLoadCandidatesForDedupe(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return { records: [] };
+  const { records } = realLoadCandidates({ repoRoot });
+  return { records };
+}
+
+/** Frontmatter form emitted by renderer.mjs: `learning-key: <value>` (no backticks, no leading dash). */
+const FRONTMATTER_LEARNING_KEY_RE = /^learning-key:\s*(.+)$/gm;
+/** Provenance-body form emitted by renderer.mjs: `` - learning-key: `<value>` ``. */
+const BODY_LEARNING_KEY_RE = /-\s*learning-key:\s*`([^`]+)`/g;
+/** Provenance-body form emitted by renderer.mjs: `` - learning-id: `<value>` ``. */
+const BODY_LEARNING_ID_RE = /-\s*learning-id:\s*`([^`]+)`/g;
+
+/**
+ * Scan `<repoRoot>/.claude/rules/*.md` for the provenance markers the
+ * renderer stamps on every machine-generated rule — the frontmatter
+ * `learning-key:` line and the body `## Provenance` block's `learning-key`/
+ * `learning-id` bullets (`renderer.mjs`) — and return the two identity sets a
+ * learning can already be materialized under. A learning whose derived
+ * `learning_key` OR raw `.id` appears in either set already has a rule file
+ * on disk: re-proposing it is the issue #484 defect (9 of 10 proposals in one
+ * run were learnings a `.claude/rules/` file already covered).
+ *
+ * Gated the same way as {@link defaultLoadCandidatesForDedupe}: an absent
+ * `repoRoot` yields empty sets rather than falling back to `process.cwd()`.
+ * Never throws — a missing `.claude/rules/` dir or an unreadable file
+ * degrades to "nothing materialized" for that source, never a crash.
+ * @param {string|undefined} repoRoot
+ * @returns {{ keys: Set<string>, ids: Set<string> }}
+ */
+function defaultReadMaterializedProvenance(repoRoot) {
+  const keys = new Set();
+  const ids = new Set();
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return { keys, ids };
+
+  const rulesDir = join(repoRoot, '.claude', 'rules');
+  let entries;
+  try {
+    entries = readdirSync(rulesDir);
+  } catch {
+    return { keys, ids }; // no rules dir yet → nothing materialized
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue;
+    let content;
+    try {
+      content = readFileSync(join(rulesDir, entry), 'utf8');
+    } catch {
+      continue; // unreadable file — skip it, do not fail the whole scan
+    }
+    for (const m of content.matchAll(FRONTMATTER_LEARNING_KEY_RE)) {
+      const v = m[1].trim();
+      if (v) keys.add(v);
+    }
+    for (const m of content.matchAll(BODY_LEARNING_KEY_RE)) {
+      const v = m[1].trim();
+      if (v) keys.add(v);
+    }
+    for (const m of content.matchAll(BODY_LEARNING_ID_RE)) {
+      const v = m[1].trim();
+      if (v && v !== 'n/a') ids.add(v);
+    }
+  }
+  return { keys, ids };
+}
+
 /**
  * Run the reconciliation engine.
  *
@@ -273,10 +459,17 @@ function warnDroppedStoreRecords(skipped) {
  *        direct learnings injection (takes precedence over `loadLearnings`).
  * @param {typeof realMergeCandidates} [opts.merge]
  *        override the sidecar merge (so tests never touch real `.orchestrator/runtime/`).
+ * @param {(repoRoot?: string) => { records: import('./idempotency.mjs').ReconcileCandidate[] }} [opts.loadCandidates]
+ *        override the idempotency-sidecar read used by the issue #484 dedupe step (below,
+ *        step 3a) — defaults to {@link defaultLoadCandidatesForDedupe} (repoRoot-gated, no
+ *        cwd fallback; see that function's doc for why).
+ * @param {(repoRoot?: string) => { keys: Set<string>, ids: Set<string> }} [opts.readMaterializedProvenance]
+ *        override the `.claude/rules/` provenance scan used by the same dedupe step —
+ *        defaults to {@link defaultReadMaterializedProvenance} (same repoRoot gate).
  * @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,
@@ -294,6 +487,12 @@ export async function runReconcile(
     // (the documented DI seam) — either location flips it on.
     const dryRun = dryRunParam === true || opts.dryRun === true;
     const merge = typeof opts.merge === 'function' ? opts.merge : realMergeCandidates;
+    const loadCandidatesForDedupe =
+      typeof opts.loadCandidates === 'function' ? opts.loadCandidates : defaultLoadCandidatesForDedupe;
+    const readMaterializedProvenance =
+      typeof opts.readMaterializedProvenance === 'function'
+        ? opts.readMaterializedProvenance
+        : defaultReadMaterializedProvenance;
     // Volume brake (#900 D) — always active; a missing/invalid override falls
     // back to the same default the Session Config parser uses.
     const maxProposalsPerRun =
@@ -331,20 +530,8 @@ export async function runReconcile(
       minInsightChars,
     });
 
-    // --- Pipeline step 3b — volume brake (#900 D) ---------------------------
-    // Sort eligible learnings by confidence DESC (ties keep their original,
-    // stable relative order) and keep only the top `maxProposalsPerRun`. The
-    // rest are cut BEFORE they ever reach the emitter — never proposed this
-    // run — and recorded as `capped` rejections in step 4b below so a report
-    // stays honest about the cut instead of silently dropping them.
     const confidenceOf = (l) =>
       l && typeof l === 'object' && typeof l.confidence === 'number' ? l.confidence : 0;
-    const sortedEligible = eligible
-      .map((learning, index) => ({ learning, index }))
-      .sort((a, b) => confidenceOf(b.learning) - confidenceOf(a.learning) || a.index - b.index)
-      .map(({ learning }) => learning);
-    const keptEligible = sortedEligible.slice(0, maxProposalsPerRun);
-    const cappedEligible = sortedEligible.slice(maxProposalsPerRun);
 
     /** @type {ReconcileProposal[]} */
     const proposals = [];
@@ -353,6 +540,92 @@ export async function runReconcile(
     /** @type {import('./idempotency.mjs').ReconcileCandidate[]} */
     const candidates = [];
 
+    // --- Pipeline step 3a — idempotency + on-disk dedupe (issue #484) ------
+    // Runs BEFORE the volume brake (step 3b) so an already-materialized
+    // learning does not consume `maxProposalsPerRun` quota that a genuinely
+    // new learning could use — the #484 defect measured on a real repo was
+    // exactly this: 9 of 10 proposals in one run were learnings that already
+    // had a `.claude/rules/` file on disk, crowding out the tenth new one.
+    // Two independent sources both count as terminal, either is sufficient:
+    //   - the idempotency sidecar already carries a `processed_at` stamp for
+    //     this `learning_key` (`isProcessed`, previously computed but NEVER
+    //     called from this module — the other half of #484);
+    //   - a `.claude/rules/*.md` file already carries a matching
+    //     `learning-key`/`learning-id` provenance marker, discovered by
+    //     scanning disk directly (covers the case where a rule was written
+    //     without ever going through this sidecar, e.g. hand-authored).
+    const { records: existingCandidates } = loadCandidatesForDedupe(repoRoot) ?? { records: [] };
+    const materialized = readMaterializedProvenance(repoRoot) ?? { keys: new Set(), ids: new Set() };
+
+    /** @type {Array<Record<string, unknown>>} */
+    const stillEligible = [];
+    let alreadyMaterialized = 0;
+
+    for (const learning of eligible) {
+      const learningKey = rejectedLearningKey(learning);
+      const learningId =
+        learning &&
+        typeof learning === 'object' &&
+        typeof learning.id === 'string' &&
+        learning.id.length > 0
+          ? learning.id
+          : null;
+
+      const sidecarTerminal =
+        learningKey !== null && isProcessed({ learning_key: learningKey }, existingCandidates);
+      const onDisk =
+        (learningKey !== null && materialized.keys.has(learningKey)) ||
+        (learningId !== null && materialized.ids.has(learningId));
+
+      if (!sidecarTerminal && !onDisk) {
+        stillEligible.push(learning);
+        continue;
+      }
+
+      alreadyMaterialized += 1;
+      const type = learningType(learning);
+      const reason = sidecarTerminal
+        ? 'already processed — the idempotency sidecar already carries a terminal verdict for this learning-key'
+        : 'already materialized — a .claude/rules/ file already carries this learning-key/learning-id';
+      rejected.push({ learningKey, type, reason, status: 'rejected' });
+
+      // Freshly discovered on-disk materialization (not yet reflected in the
+      // sidecar): stamp it terminal now so a FUTURE run's `isProcessed()`
+      // check catches it without re-scanning `.claude/rules/` every time.
+      // Routed through the SAME `candidates` array + `merge()` call as every
+      // other record produced this run (step 6 below), so — like everything
+      // else here — it is skipped entirely under `dryRun`; this is not a
+      // second write path.
+      if (onDisk && !sidecarTerminal && learningKey !== null) {
+        const stamped = buildCandidate({
+          id: makeCandidateId(learningKey, `materialized-${type}`),
+          learningKey,
+          slug: '',
+          status: 'proposed',
+          reason,
+          confidence: confidenceOf(learning),
+          createdAt,
+        });
+        stamped.processed_at = createdAt;
+        stamped.outcome = 'already-on-disk';
+        candidates.push(stamped);
+      }
+    }
+
+    // --- Pipeline step 3b — volume brake (#900 D) ---------------------------
+    // Sort STILL-eligible learnings (post-dedupe) by confidence DESC (ties
+    // keep their original, stable relative order) and keep only the top
+    // `maxProposalsPerRun`. The rest are cut BEFORE they ever reach the
+    // emitter — never proposed this run — and recorded as `capped`
+    // rejections in step 4b below so a report stays honest about the cut
+    // instead of silently dropping them.
+    const sortedEligible = stillEligible
+      .map((learning, index) => ({ learning, index }))
+      .sort((a, b) => confidenceOf(b.learning) - confidenceOf(a.learning) || a.index - b.index)
+      .map(({ learning }) => learning);
+    const keptEligible = sortedEligible.slice(0, maxProposalsPerRun);
+    const cappedEligible = sortedEligible.slice(maxProposalsPerRun);
+
     // --- Pipeline step 4 — per eligible learning (wrapped per-item) ---------
     for (const learning of keptEligible) {
       try {
@@ -499,6 +772,7 @@ export async function runReconcile(
       proposed: proposals.length,
       rejected: rejected.length,
       capped: cappedEligible.length,
+      alreadyMaterialized,
       written,
     };
     // Additive + absence-preserving: the key exists ONLY when the store was
@@ -512,3 +786,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);
+}