session-orchestrator 3.23.0 → 4.0.0

package/scripts/dialectic-deriver.mjs

@@ -47,6 +47,8 @@ import { randomBytes } from 'node:crypto';
 
 import { readPeerCards } from './lib/peer-cards/reader.mjs';
 import { filterRealSessions } from './lib/session-schema/filters.mjs';
+import { readCanonicalSessions } from './lib/sessions-canonical.mjs';
+import { recordDialecticRun } from './lib/learnings/evolve-telemetry.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -174,6 +176,30 @@ function countContentLines(body) {
   return n;
 }
 
+/**
+ * Count the peer-card sections a proposed diff body would change (#1206 —
+ * `orchestrator.dialectic.completed`'s `user_deltas` / `agent_deltas` in
+ * dry-run mode, where there is no `mergePeerCard()` stats object to read).
+ * Pure function — no I/O.
+ *
+ * Counts `<!-- BEGIN MANAGED: <name> -->` sentinels (the same grammar
+ * `scripts/lib/peer-cards/merger.mjs` parses). A proposed body that carries
+ * none — the LLM emits a bare full-body replacement per the current prompt
+ * contract in {@link buildPrompt}, not per-section sentinels — still counts
+ * as ONE delta: a non-empty full-body replacement is a real change to the
+ * target, and an empty proposed body counts as zero (nothing to report for a
+ * target the response never touched).
+ *
+ * @param {string | undefined} diffText — `diff.user` or `diff.agent` from
+ *   {@link parseResponse}; `undefined` when the target was not emitted.
+ * @returns {number}
+ */
+export function countManagedSections(diffText) {
+  if (typeof diffText !== 'string' || diffText.length === 0) return 0;
+  const matches = diffText.match(/<!--\s*BEGIN\s+MANAGED:\s*[\w-]+\s*-->/g);
+  return matches && matches.length > 0 ? matches.length : 1;
+}
+
 /**
  * Assemble the prompt-ready payload object. Pure function — no I/O.
  *
@@ -393,19 +419,25 @@ async function readTopLearnings(repoRoot, topN) {
 }
 
 /**
- * Read and rank sessions: filter out phantom `status: 'abandoned'` stubs
- * (#834, session-close-backfill), sort by `completed_at` DESC, take last K.
+ * Read and rank sessions: collapse ledger duplicates (#1209 — the ledger is
+ * append-only and can carry more than one raw line per physical session, see
+ * `scripts/lib/sessions-canonical.mjs` header), filter out phantom
+ * `status: 'abandoned'` stubs (#834, session-close-backfill), sort by
+ * `completed_at` DESC, take last K.
+ *
+ * Without the dedup, a duplicate ledger line for the SAME session can occupy
+ * two of the K context slots and evict a genuinely distinct, older session.
+ * Without the phantom filter, phantoms (0 waves, seconds of runtime) can
+ * displace REAL session context out of the K-window the derivation prompt sees.
  *
- * Without the filter, phantoms (0 waves, seconds of runtime) can displace
- * REAL session context out of the K-window the derivation prompt sees.
+ * Synchronous — `readCanonicalSessions()` reads the file itself.
  *
  * @param {string} repoRoot
  * @param {number} lastK
- * @returns {Promise<Array<object>>}
+ * @returns {Array<object>}
  */
-async function readLastSessions(repoRoot, lastK) {
-  const path = join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
-  const entries = filterRealSessions(await readJsonlBestEffort(path));
+function readLastSessions(repoRoot, lastK) {
+  const entries = filterRealSessions(readCanonicalSessions({ repoRoot }));
   entries.sort((a, b) => {
     const ta = typeof a?.completed_at === 'string' ? a.completed_at : '';
     const tb = typeof b?.completed_at === 'string' ? b.completed_at : '';
@@ -488,6 +520,15 @@ export async function runDialecticDeriver({
     throw new TypeError('runDialecticDeriver: repoRoot (absolute path) is required');
   }
 
+  // #1206 — telemetry start marker for the mechanical `orchestrator.dialectic.
+  // completed` emits below. Mechanical (measured), not the coordinator's own
+  // typed DURATION_MS placeholder — covers every return path THIS function
+  // can determine on its own; see the module header for the two abort classes
+  // (`unknown-model`, thrown above; `subagent-crash`) and APPLY-mode success
+  // that only the skill-prose caller can record (merge + Agent() dispatch
+  // both happen one layer up, outside this pure pipeline).
+  const t0 = Date.now();
+
   // Gate 1: model fail-fast. Throws Error with the canonical message.
   validateModel(model);
 
@@ -516,6 +557,7 @@ export async function runDialecticDeriver({
     && (peerCards.agent === null || peerCards.agent === undefined)
     && (steering === null || steering === undefined)
   ) {
+    await recordDialecticRun({ repoRoot, status: 'empty-input', durationMs: Date.now() - t0 });
     return { status: 'empty-input', skipped_reason: 'no-input', diff: {} };
   }
 
@@ -533,6 +575,7 @@ export async function runDialecticDeriver({
   const estimatedInput = estimateInputTokens(prompt);
   const verdict = checkBudget(estimatedInput, budget);
   if (verdict.ok === false) {
+    await recordDialecticRun({ repoRoot, status: 'budget-exceeded', durationMs: Date.now() - t0 });
     return {
       status: 'budget-exceeded',
       used: verdict.used,
@@ -551,6 +594,7 @@ export async function runDialecticDeriver({
 
   // Gate 4: would-empty-card — refuse unless caller passed allowEmptying.
   if (!allowEmptying && detectEmptying(diff, peerCards)) {
+    await recordDialecticRun({ repoRoot, status: 'would-empty-card', durationMs: Date.now() - t0 });
     return {
       status: 'would-empty-card',
       skipped_reason: 'detected-empty-card-target',
@@ -563,6 +607,27 @@ export async function runDialecticDeriver({
     };
   }
 
+  // #1206 success telemetry — DRY-RUN ONLY. `diff` here is the run's FINAL
+  // artefact in dry-run mode (Step 6.4 writes it verbatim to
+  // `.orchestrator/dialectic-pending.md`), so the delta counts are knowable
+  // right here via the pure `countManagedSections()` helper. In APPLY mode
+  // the artefact is NOT final yet — `mergePeerCard()` still has to run, and
+  // that happens one layer up in `skills/evolve/SKILL.md` Step 6.4 — so the
+  // success emit for that branch is that caller's job, using the SAME
+  // `recordDialecticRun()` with the real merge-stats deltas.
+  if (dryRun) {
+    await recordDialecticRun({
+      repoRoot,
+      status: 'ok',
+      mode: 'dry-run',
+      userDeltas: countManagedSections(diff.user),
+      agentDeltas: countManagedSections(diff.agent),
+      tokensIn: response?.usage?.input_tokens,
+      tokensOut: response?.usage?.output_tokens,
+      durationMs: Date.now() - t0,
+    });
+  }
+
   return {
     status: 'ok',
     diff,

package/scripts/emit-event.mjs

@@ -22,7 +22,8 @@
  *
  * Exit codes (per .claude/rules/cli-design.md):
  *   0 — success (event emitted)
- *   1 — user/input error (missing --type, malformed --payload JSON, non-object payload)
+ *   1 — user/input error (missing --type, malformed --payload JSON, non-object
+ *       payload, or a record rejected by validateEventRecord — #1177)
  *   2 — system error (write failure, unexpected internal error)
  *
  * Data → stdout (only with --json). Diagnostics → stderr (always). Related: #611.
@@ -49,7 +50,8 @@ Flags:
 
 Exit codes:
   0 — success
-  1 — user/input error (missing --type, malformed --payload, non-object payload)
+  1 — user/input error (missing --type, malformed --payload, non-object payload,
+      or an event record rejected by the events schema)
   2 — system error (write failure / internal error)
 `;
 
@@ -147,6 +149,12 @@ try {
 try {
   await emitEvent(type, payload, filePath ? { filePath } : {});
 } catch (err) {
+  // A schema-validation rejection is a USER/INPUT error (bad --type or a
+  // payload key colliding with the schema) — exit 1, not 2. Nothing was
+  // written: emitEvent validates before it touches the filesystem (#1177).
+  if (err?.name === 'EventValidationError') {
+    fail(`invalid event: ${err.message}`, 1, jsonMode);
+  }
   // Write/IO failures are system errors (exit 2).
   fail(`failed to emit event: ${err.message}`, 2, jsonMode);
 }

package/scripts/export-hw-learnings.mjs

@@ -62,6 +62,7 @@ import { findProjectRoot, resolveInstructionFile, expandTilde } from './lib/comm
 import { parseSessionConfig } from './lib/config.mjs';
 import { createSecretValueMasker } from './lib/secret-masker.mjs';
 import { stableHostname, readHostAliases } from './lib/host-identity.mjs';
+import { emitEvent, sessionAttribution } from './lib/events.mjs';
 
 // Vault-relative default write target (Epic #774 — docs Public-Split removed
 // the prior in-repo generated telemetry doc in favor of the private Meta-Vault).
@@ -310,6 +311,15 @@ export function redactLocalHostNames(s, names) {
  */
 let _secretMasker = null;
 
+/**
+ * Learning entries handed to `anonymizeLearning` this process. Counts only
+ * (#1028 residue 2) — mirrors `_maskedRecords` in
+ * `scripts/lib/vault-mirror/process.mjs`.
+ */
+let _maskedRecords = 0;
+/** String values this process that masking actually CHANGED. Counts only. */
+let _maskHits = 0;
+
 /**
  * Mask env-derived secret VALUES in a free-form string.
  *
@@ -322,7 +332,68 @@ let _secretMasker = null;
 function maskSecretValues(s) {
   if (typeof s !== 'string') return s;
   if (_secretMasker === null) _secretMasker = createSecretValueMasker(process.env);
-  return _secretMasker.mask(s);
+  const masked = _secretMasker.mask(s);
+  if (masked !== s) _maskHits++;
+  return masked;
+}
+
+/**
+ * Counts-only view of the masking that happened in this process (#1028
+ * residue 2). FORCE-BUILDS the masker rather than reporting 0 for an unbuilt
+ * one — same reasoning as `getMaskerStats()` in
+ * `scripts/lib/vault-mirror/process.mjs`: at 0 anonymized entries the lazy
+ * build in `maskSecretValues` above never fires, and a `needle_count: 0` from
+ * that path would be indistinguishable from "this channel has no masking
+ * wired at all" — the exact ambiguity the telemetry exists to remove.
+ *
+ * NEVER returns a needle, a prefix of one, or any masked text — only cardinals.
+ *
+ * @returns {{ needleCount: number, records: number, hits: number }}
+ */
+function getExportMaskerStats() {
+  if (_secretMasker === null) _secretMasker = createSecretValueMasker(process.env);
+  return { needleCount: _secretMasker.needleCount, records: _maskedRecords, hits: _maskHits };
+}
+
+/**
+ * Emit this channel's `orchestrator.secret_masker.applied` record — the third
+ * of the three masker channels (`vault-mirror`, `narrative-mirror`,
+ * `export-hw-learnings`) to wire it (#1028 residue 2). Same core field set as
+ * the sibling channels (`channel`, `needle_count`, `records`, `hits`,
+ * `dry_run`), plus `session_id`/`semantic_session_id` via `sessionAttribution`
+ * — matching the `narrative-mirror` channel's shape, since this CLI (like
+ * `mirrorNarrative`) always resolves a concrete `repoRoot` to attribute
+ * against, unlike the `vault-mirror` CLI's 2-arg `emitEvent` call.
+ *
+ * `repoRoot` is REQUIRED here rather than left to `emitEvent`'s own
+ * cwd-derived default (#941/#1147) — a bare 2-arg call would attribute a run
+ * to whatever directory the process happens to sit in rather than to the repo
+ * whose `learnings.jsonl` was actually exported.
+ *
+ * Best-effort: never throws, never alters the export/promote result.
+ *
+ * @param {{ repoRoot: string, dryRun: boolean }} opts
+ * @returns {Promise<void>}
+ */
+async function emitMaskerTelemetry({ repoRoot, dryRun }) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
+  try {
+    const stats = getExportMaskerStats();
+    await emitEvent(
+      'orchestrator.secret_masker.applied',
+      {
+        channel: 'export-hw-learnings',
+        needle_count: stats.needleCount,
+        records: stats.records,
+        hits: stats.hits,
+        dry_run: !!dryRun,
+        ...sessionAttribution(repoRoot),
+      },
+      { repoRoot },
+    );
+  } catch {
+    /* Best-effort telemetry — a broken ledger must never fail the export. */
+  }
 }
 
 /**
@@ -379,6 +450,11 @@ export function bucketCpuPct(pct) {
  */
 export function anonymizeLearning(entry) {
   const e = normalizeLearning(entry);
+  // #1028 residue 2: counted BEFORE the masking calls below, unconditionally —
+  // "records handed to the masker choke-point" must not depend on whether this
+  // particular entry's insight/evidence happened to contain a needle. Mirrors
+  // `_maskedRecords++` in `scripts/lib/vault-mirror/process.mjs`.
+  _maskedRecords++;
   const out = {
     ...e,
     // #1025: value-mask BEFORE form-anonymize — see the ORDER IS LOAD-BEARING
@@ -488,6 +564,11 @@ function parseArgs(argv) {
     input: '.orchestrator/metrics/learnings.jsonl',
     output: undefined, // resolved lazily below (default = vault-dir target)
     generatedAt: new Date().toISOString(),
+    // #1028 residue 2: resolved explicitly HERE, at the CLI boundary, so the
+    // masker-telemetry emit in promoteHwLearnings/exportHwLearnings gets a
+    // real repoRoot — those library functions deliberately never default it
+    // themselves (see their opts.repoRoot doc for why).
+    repoRoot: findProjectRoot(),
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -541,9 +622,18 @@ function parseArgs(argv) {
  * @param {object} opts
  * @param {string} opts.input — path to learnings.jsonl
  * @param {boolean} opts.dryRun — if true, do not write any files
+ * @param {string} [opts.repoRoot] — repo whose ledger the masker-telemetry
+ *   event (#1028 residue 2) is pinned to. EXPLICIT ONLY — never defaulted to
+ *   `findProjectRoot()`/cwd inside this library function (#941/#1147: a
+ *   silent cwd-derived default is exactly what let earlier callers, including
+ *   plain test invocations, write into whichever repo the process happened to
+ *   sit in). The CLI entrypoint below resolves and passes it explicitly;
+ *   library callers that omit it simply get no masker-telemetry emit — see
+ *   `emitMaskerTelemetry`'s own repoRoot guard.
  * @returns {Promise<{promoted: number, skipped: number, flags: string[]}>}
  */
 export async function promoteHwLearnings(opts) {
+  const repoRoot = opts.repoRoot;
   const { entries, malformed } = await readLearnings(opts.input);
 
   const hwPrivate = filterByScope(filterByType(entries, 'hardware-pattern'), 'private');
@@ -555,6 +645,10 @@ export async function promoteHwLearnings(opts) {
   }
 
   if (hwPrivate.length === 0) {
+    // #1028 residue 2: emitted here too — a run that anonymizes 0 entries
+    // still ran, and `getExportMaskerStats()` force-builds the masker so
+    // `needle_count` is real even though `_maskedRecords` stays 0.
+    await emitMaskerTelemetry({ repoRoot, dryRun: !!opts.dryRun });
     return { promoted: 0, skipped: hwPublicExisting.length, flags };
   }
 
@@ -595,10 +689,23 @@ export async function promoteHwLearnings(opts) {
     await rewriteLearnings(opts.input, allEntries);
   }
 
+  // #1028 residue 2: one masker-telemetry record per promote run.
+  await emitMaskerTelemetry({ repoRoot, dryRun: !!opts.dryRun });
+
   return { promoted: promotedEntries.length, skipped: hwPublicExisting.length, flags };
 }
 
+/**
+ * @param {object} opts
+ * @param {string} opts.input — path to learnings.jsonl
+ * @param {string} opts.output — write target
+ * @param {boolean} opts.dryRun — if true, do not write any files
+ * @param {string} opts.generatedAt — ISO timestamp for the rendered doc
+ * @param {string} [opts.repoRoot] — see `promoteHwLearnings` opts.repoRoot doc.
+ * @returns {Promise<{markdown: string, count: number}>}
+ */
 export async function exportHwLearnings(opts) {
+  const repoRoot = opts.repoRoot;
   const { entries } = await readLearnings(opts.input);
   const hwPublic = filterByScope(filterByType(entries, 'hardware-pattern'), 'public');
   const anonymized = hwPublic.map((e) => anonymizeLearning(e));
@@ -608,6 +715,11 @@ export async function exportHwLearnings(opts) {
     await mkdir(path.dirname(opts.output), { recursive: true });
     await writeFile(opts.output, md, 'utf8');
   }
+  // #1028 residue 2: one masker-telemetry record per export run, whether or
+  // not any hardware-pattern entry was actually public (`hwPublic.length`
+  // can legitimately be 0 — `getExportMaskerStats()` still force-builds the
+  // masker so `needle_count` is a real measured value).
+  await emitMaskerTelemetry({ repoRoot, dryRun: !!opts.dryRun });
   return { markdown: md, count: hwPublic.length };
 }