session-orchestrator 5.2.0 → 5.4.0

package/scripts/lib/skill-evolution/candidate-intake.mjs

@@ -6,10 +6,18 @@
  *   1. `/evolve` learnings (`.orchestrator/metrics/learnings.jsonl` records)
  *   2. `claude-md-drift-check` output (`driftResult.errors[]`)
  *
- * This module is a PURE transform: it performs NO I/O. It never reads or writes
- * any file. Persistence and the `processed_at` / `superseded_by` lifecycle are
- * OWNED BY the sibling `idempotency.mjs` module — this module only emits the
- * raw candidates with those fields nulled out.
+ * This module WRITES nothing. Its only read is target resolution for the
+ * learnings feeder: at most one `git ls-files` per `extractCandidates` call
+ * (lazy — only when a learning survives the cheaper filters), plus a
+ * `realpathSync` containment check that applies with or without git. A
+ * learning becomes a candidate only when its extracted path resolves — symlinks
+ * followed — to a regular file inside the realpath of `repoRoot` that is also
+ * the ONE tracked file it names (tracking is skipped when git is unavailable);
+ * the kept `target_path` is the repo-relative form of that resolved file, so a
+ * bare basename becomes its full path and `scripts/../x.mjs` becomes `x.mjs`. Persistence and
+ * the `processed_at` / `superseded_by` lifecycle are OWNED BY the sibling
+ * `idempotency.mjs` module — this module only emits the raw candidates with
+ * those fields nulled out.
  *
  * The `id` field is a deterministic short hash of (source, target_path,
  * fingerprint), so the same input always yields the same id. That determinism
@@ -18,7 +26,10 @@
  * Part of Epic #643 → issue #647 (C2 auto-repair engine).
  */
 
+import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
+import { realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
 
 /**
  * @typedef {Object} RepairCandidate
@@ -96,6 +107,104 @@ function extractPath(text) {
   return match ? match[0] : null;
 }
 
+/**
+ * Build the target resolver for ONE extraction run. `PATH_RE` also admits bare
+ * basenames (`engine.mjs`, `mcp.json`) that exist nowhere at the repo root, so
+ * an extracted path is a claim, not a target, until it resolves here.
+ *
+ * Resolution is fail-closed — `null` drops the candidate. In BOTH modes the
+ * path is resolved with `realpathSync` (every symlink followed) and must land
+ * on a regular file inside `realpathSync(repoRoot)`; any resolution error
+ * drops it. The kept `target_path` is the repo-relative POSIX form of that
+ * RESOLVED path, so `scripts/../CLAUDE.md` and `CLAUDE.md` name one target
+ * (and mint one id). Containment follows `classifyTarget` in
+ * `blast-radius-classifier.mjs`, plus the realpath of the target itself.
+ *
+ * With git, the resolved path must additionally be a tracked file:
+ *   - a path containing `/` is resolved as given;
+ *   - a bare basename must match exactly ONE tracked file (zero = unresolvable,
+ *     two or more = ambiguous) and is resolved from that file's full path.
+ * A tracked symlink whose target lies outside the repo is therefore dropped.
+ *
+ * The tracked-file index is read lazily and at most once per resolver
+ * (`git ls-files -z` in `repoRoot`), so a run without a qualifying learning
+ * never spawns git. Without git (binary missing, not a repository) only the
+ * realpath containment applies — a bare basename then resolves only at the
+ * root, since nothing enumerates the tree.
+ *
+ * @param {string} repoRoot
+ * @returns {(extracted: string) => string|null}
+ */
+function makeTargetResolver(repoRoot) {
+  /** @type {{ tracked: Set<string>, byBasename: Map<string, string[]> }|null|undefined} */
+  let index; // undefined = not read yet, null = git unavailable
+
+  // Canonicalise the root once, as blast-radius-classifier does: a symlinked
+  // repoRoot (macOS /var → /private/var) must still anchor the escape check.
+  let root;
+  try {
+    root = realpathSync(path.resolve(repoRoot));
+  } catch {
+    root = path.resolve(repoRoot);
+  }
+
+  function readIndex() {
+    try {
+      const out = execFileSync('git', ['ls-files', '-z'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      const tracked = new Set(out.split('\0').filter(Boolean));
+      /** @type {Map<string, string[]>} */
+      const byBasename = new Map();
+      for (const file of tracked) {
+        const base = file.slice(file.lastIndexOf('/') + 1);
+        const list = byBasename.get(base);
+        if (list) list.push(file);
+        else byBasename.set(base, [file]);
+      }
+      return { tracked, byBasename };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Realpath-resolve `rel` against the canonical root.
+   * @param {string} rel
+   * @returns {string|null} repo-relative POSIX path of the regular file it
+   *   resolves to, or null when it escapes the root, is not a regular file, or
+   *   does not resolve at all.
+   */
+  function resolveInsideRoot(rel) {
+    let real;
+    try {
+      real = realpathSync(path.resolve(root, rel));
+      if (!statSync(real).isFile()) return null;
+    } catch {
+      return null;
+    }
+    const back = path.relative(root, real);
+    if (back === '' || back.startsWith('..') || path.isAbsolute(back)) return null;
+    return back.split(path.sep).join('/');
+  }
+
+  return (extracted) => {
+    if (index === undefined) index = readIndex();
+    if (index === null) return resolveInsideRoot(extracted);
+    let candidate = extracted;
+    if (!extracted.includes('/')) {
+      const matches = index.byBasename.get(extracted) ?? [];
+      if (matches.length !== 1) return null;
+      candidate = matches[0];
+    }
+    const resolved = resolveInsideRoot(candidate);
+    return resolved !== null && index.tracked.has(resolved) ? resolved : null;
+  };
+}
+
 /**
  * Map a single learning record to a RepairCandidate, or null when it fails any
  * actionable filter. learnings.jsonl records are NOT uniform — only `confidence`
@@ -104,9 +213,10 @@ function extractPath(text) {
  * @param {Record<string, unknown>} learning
  * @param {number} evidenceFloor
  * @param {string} nowIso
+ * @param {(extracted: string) => string|null} resolveTarget
  * @returns {RepairCandidate|null}
  */
-function learningToCandidate(learning, evidenceFloor, nowIso) {
+function learningToCandidate(learning, evidenceFloor, nowIso, resolveTarget) {
   if (!learning || typeof learning !== 'object') return null;
 
   // Filter 1: confidence gate.
@@ -123,13 +233,18 @@ function learningToCandidate(learning, evidenceFloor, nowIso) {
   const subject = typeof learning.subject === 'string' ? learning.subject : '';
   const insight = typeof learning.insight === 'string' ? learning.insight : '';
 
-  // Filter 2: resolvable target path from subject OR insight.
-  const targetPath = extractPath(subject) ?? extractPath(insight);
-  if (!targetPath) return null;
+  // Filter 2: a path-shaped token in subject OR insight.
+  const extracted = extractPath(subject) ?? extractPath(insight);
+  if (!extracted) return null;
 
   // Filter 3: insight must be prescriptive.
   if (!PRESCRIPTIVE_RE.test(insight)) return null;
 
+  // Filter 5: the token resolves to exactly one tracked file (last — it is the
+  // only filter that may spawn git).
+  const targetPath = resolveTarget(extracted);
+  if (!targetPath) return null;
+
   const source = 'evolve-learning';
   const sourceRef = typeof learning.id === 'string' && learning.id.length > 0
     ? learning.id
@@ -218,7 +333,9 @@ function driftErrorToCandidate(err, nowIso) {
 
 /**
  * Ingest the two repair-candidate feeders and return a normalised
- * `RepairCandidate[]`. Pure transform — performs no I/O.
+ * `RepairCandidate[]`. Writes nothing; learnings are resolved against the files
+ * tracked in `repoRoot` (see `makeTargetResolver`). Drift errors pass through
+ * unresolved — the checker reported them from a file it read.
  *
  * @param {Object} params
  * @param {Array<Record<string, unknown>>} [params.learnings] - `/evolve` learning records.
@@ -226,7 +343,10 @@ function driftErrorToCandidate(err, nowIso) {
  *        claude-md-drift-check output. Only `errors[]` are mapped; `warnings[]`
  *        are skipped. A null result, or a status of `skipped`/`skipped-mode-off`/
  *        undefined, emits zero drift candidates.
- * @param {string} [params.repoRoot] - repo root (accepted for caller symmetry; unused in the pure transform).
+ * @param {string} [params.repoRoot] - repo root learning targets must resolve in
+ *        (default `process.cwd()`). A learning is dropped unless its extracted
+ *        path realpath-resolves to a regular file inside this root that is
+ *        exactly one tracked file there (tracking skipped without git).
  * @param {number} [params.evidenceFloor=0.5] - minimum learning confidence to qualify.
  * @param {string} [params.now] - ISO timestamp for `created_at` + expiry checks (test determinism).
  * @returns {RepairCandidate[]}
@@ -234,13 +354,14 @@ function driftErrorToCandidate(err, nowIso) {
 export function extractCandidates({
   learnings,
   driftResult,
-  // eslint-disable-next-line no-unused-vars -- accepted for caller symmetry; pure transform does no path resolution
   repoRoot,
   evidenceFloor = 0.5,
   now,
 } = {}) {
   const nowIso = typeof now === 'string' && now.length > 0 ? now : new Date().toISOString();
   const floor = Number.isFinite(evidenceFloor) ? evidenceFloor : 0.5;
+  const root = typeof repoRoot === 'string' && repoRoot.length > 0 ? repoRoot : process.cwd();
+  const resolveTarget = makeTargetResolver(root);
 
   /** @type {RepairCandidate[]} */
   const candidates = [];
@@ -248,7 +369,7 @@ export function extractCandidates({
   // Feeder 1: /evolve learnings.
   if (Array.isArray(learnings)) {
     for (const learning of learnings) {
-      const candidate = learningToCandidate(learning, floor, nowIso);
+      const candidate = learningToCandidate(learning, floor, nowIso, resolveTarget);
       if (candidate) candidates.push(candidate);
     }
   }

package/scripts/lib/skill-evolution/engine.mjs

@@ -8,7 +8,7 @@
  * — the matrix is the load-bearing deliverable, not the file-write mechanics.
  *
  * COMPOSITION (the five siblings, all DI-injectable via `opts`):
- *   - candidate-intake.mjs       → extractCandidates    (pure transform)
+ *   - candidate-intake.mjs       → extractCandidates    (no writes; resolves targets against repoRoot)
  *   - idempotency.mjs            → mergeCandidates / markProcessed / isProcessed
  *                                   / loadCandidates    (store I/O + supersession)
  *   - blast-radius-classifier.mjs→ classifyTarget       (R5 posture/gate triple)
@@ -17,7 +17,7 @@
  *
  * PIPELINE:
  *   extractCandidates(learnings, driftResult)
- *     → mergeCandidates (persist + supersede)
+ *     → mergeCandidates (persist + supersede; skipped under dryRun)
  *     → for each NON-processed candidate:
  *         classify → decide per matrix → act
  *
@@ -583,7 +583,8 @@ async function finishOpenMr({ candidate, candidateId, targetPath, targetType, re
  * @param {Array<Record<string, unknown>>} [params.learnings] — `/evolve` learning records.
  * @param {{ status?: string, errors?: Array<Record<string, unknown>> }|null} [params.driftResult]
  *        claude-md-drift-check output.
- * @param {boolean} [params.dryRun=false] — when true, no mutation/MR/stamp; previews only.
+ * @param {boolean} [params.dryRun=false] — when true, no mutation/MR/stamp and no
+ *        candidate-store write (the skip is logged via `opts.log`); previews only.
  * @param {Object} [opts] — DI seams (all default to the real sibling functions).
  * @param {typeof realExtractCandidates} [opts.extractCandidates]
  * @param {typeof realMergeCandidates} [opts.mergeCandidates]
@@ -629,7 +630,7 @@ export async function runRepairEngine(
   const outcomes = [];
   const summary = { autonomousApplied: 0, mrsOpened: 0, advisories: 0, blocked: 0, total: 0 };
 
-  // --- Pipeline step 1 — intake (pure transform) ---------------------------
+  // --- Pipeline step 1 — intake (no writes; repoRoot anchors target resolution)
   let candidates;
   try {
     candidates = seams.extractCandidates({
@@ -650,11 +651,19 @@ export async function runRepairEngine(
   }
 
   // --- Pipeline step 2 — merge (persist + supersede) -----------------------
-  try {
-    seams.mergeCandidates({ candidates, repoRoot });
-  } catch (err) {
-    seams.log('error', `engine: mergeCandidates threw — ${err?.message ?? err}`);
-    // Persistence failure is non-fatal: continue with the in-memory candidates.
+  // A dry run previews from the in-memory candidates and never writes the store.
+  if (dryRun === true) {
+    seams.log(
+      'info',
+      `engine: dry-run — candidate store write skipped (${candidates.length} candidate(s) not persisted)`,
+    );
+  } else {
+    try {
+      seams.mergeCandidates({ candidates, repoRoot });
+    } catch (err) {
+      seams.log('error', `engine: mergeCandidates threw — ${err?.message ?? err}`);
+      // Persistence failure is non-fatal: continue with the in-memory candidates.
+    }
   }
 
   // --- Pipeline step 3 — per-candidate classify → decide → act -------------

package/scripts/lib/skill-judge.mjs

@@ -31,6 +31,7 @@
  *  - estimateInputTokens(str)          — char-count/4 heuristic
  *  - checkBudget(estimated, budget)    — verdict for the budget gate
  *  - buildJudgePrompt(skills, tail, nonce) — pure prompt assembly (untrusted-data fence)
+ *  - evidenceBudgetChars(skills, budget)   — characters left for evidence after the prompt frame
  *  - parseJudgeResponse(text)          — extract one fenced ```json block, validate, drop malformed
  */
 
@@ -54,6 +55,9 @@ export const DEFAULT_BUDGET = Object.freeze({ input: 8000, output: 4000 });
 /** Industry-standard heuristic: ~4 chars per token for English prose. */
 const CHARS_PER_TOKEN = 4;
 
+/** Hex length of the per-call untrusted-data nonce (`randomBytes(16)` → 32 hex). */
+const NONCE_HEX_LENGTH = 32;
+
 // ---------------------------------------------------------------------------
 // Pure-function gates
 // ---------------------------------------------------------------------------
@@ -182,6 +186,25 @@ export function buildJudgePrompt(selectedSkills, transcriptTail, nonce) {
   ].join('\n');
 }
 
+/**
+ * How many characters of evidence fit inside `budget.input` for THIS judged set.
+ *
+ * The caller must not have to guess: the prompt frame is MEASURED by building
+ * the very prompt that will be sent with an empty fence, so the answer tracks
+ * every future edit to `buildJudgePrompt` automatically. The nonce is
+ * length-accurate (`NONCE_HEX_LENGTH`) rather than the real random value, since
+ * only its length affects the frame.
+ *
+ * @param {string[]} selectedSkills — the judged set (its JSON is part of the frame)
+ * @param {{input?: number}} [budget]
+ * @returns {number} characters available for `evidence.text` (never negative)
+ */
+export function evidenceBudgetChars(selectedSkills = [], budget = DEFAULT_BUDGET) {
+  const maxInput = typeof budget?.input === 'number' ? budget.input : DEFAULT_BUDGET.input;
+  const frame = buildJudgePrompt(selectedSkills, '', 'f'.repeat(NONCE_HEX_LENGTH)).length;
+  return Math.max(0, maxInput * CHARS_PER_TOKEN - frame);
+}
+
 /**
  * Parse the judge response into validated judgment records. Extracts the FIRST
  * fenced ```json block, JSON.parses it, and validates each entry against
@@ -253,7 +276,7 @@ export function parseJudgeResponse(text) {
 
 /**
  * @typedef {Object} JudgeResult
- * @property {'ok' | 'empty-input' | 'budget-exceeded'} status
+ * @property {'ok' | 'empty-input' | 'no-evidence' | 'budget-exceeded'} status
  * @property {Array<{skill: string, applied: string, completed: string, confidence: number}>} judgments
  * @property {{input_tokens?: number, output_tokens?: number, estimated_input?: number}} [usage]
  * @property {string} [skipped_reason]
@@ -269,6 +292,7 @@ export function parseJudgeResponse(text) {
  *
  * Control flow (matches the ratified #645 L3 contract):
  *   - empty selectedSkills → {status:'empty-input', judgments:[]} (no dispatch).
+ *   - empty evidence text  → {status:'no-evidence', judgments:[]} (no dispatch, #1399).
  *   - budget exceeded     → {status:'budget-exceeded', judgments:[]} (no dispatch,
  *                            NOT truncated — mirrors dialectic-deriver).
  *   - else → dispatch → parse → {status:'ok', judgments, usage}.
@@ -277,7 +301,8 @@ export function parseJudgeResponse(text) {
  * @param {(args: {model: string, prompt: string, maxTokens: number}) => Promise<{text: string, usage?: {input_tokens?: number, output_tokens?: number}}>} opts.dispatchAgent — REQUIRED, injected DI boundary
  * @param {string} [opts.repoRoot]
  * @param {string|null} [opts.sessionId]
- * @param {string} [opts.transcriptTail]
+ * @param {{text?: string}} [opts.evidence] — preferred input; `buildSkillEvidence()` output (#1399)
+ * @param {string} [opts.transcriptTail] — legacy raw-string input; used when `evidence` is absent
  * @param {string[]} [opts.selectedSkills]
  * @param {'haiku'|'sonnet'|'opus'} [opts.model='haiku']
  * @param {{input: number, output: number}} [opts.budget]
@@ -293,6 +318,7 @@ export async function runSkillJudge({
   // `_`-prefixed names so the contract keys stay documented without tripping no-unused-vars.
   repoRoot: _repoRoot,
   sessionId: _sessionId,
+  evidence,
   transcriptTail = '',
   selectedSkills = [],
   model = 'haiku',
@@ -313,8 +339,24 @@ export async function runSkillJudge({
     return { status: 'empty-input', judgments: [], skipped_reason: 'no-selected-skills' };
   }
 
+  // Gate 2b (#1399): empty evidence — do NOT dispatch. Measured 2026-09-19 at
+  // `8f15f77b`: a prompt whose fence is empty is 1387 chars = 346 estimated
+  // tokens, so the budget gate below waves it through and the judge is asked to
+  // rule on a transcript it was never shown. An advisory verdict from no
+  // evidence is worse than no verdict — it looks exactly like a real one in
+  // `skill-judgments.jsonl`.
+  const evidenceText =
+    typeof evidence?.text === 'string' && evidence.text.trim()
+      ? evidence.text
+      : typeof transcriptTail === 'string'
+        ? transcriptTail
+        : '';
+  if (!evidenceText.trim()) {
+    return { status: 'no-evidence', judgments: [], skipped_reason: 'empty-transcript-evidence' };
+  }
+
   const nonce = randomNonce();
-  const prompt = buildJudgePrompt(skills, transcriptTail, nonce);
+  const prompt = buildJudgePrompt(skills, evidenceText, nonce);
 
   // Gate 3: budget — fail-fast BEFORE dispatch when the prompt would exceed it.
   const estimatedInput = estimateInputTokens(prompt);

package/scripts/lib/subagents-schema.mjs

@@ -42,8 +42,16 @@
  *   token_cache_creation  integer | null — `usage.cache_creation_input_tokens` (v2+)
  *   token_output      integer | null — completion token count for this subagent
  *   model             string  | null — model id from the transcript (v2+); null when
- *                                      the transcript exposes none. Required to price
- *                                      the record — see scripts/lib/telemetry/pricing.mjs.
+ *                                      the transcript exposes none, or when its token-
+ *                                      bearing turns used two or more models or one turn
+ *                                      named none (#1470). Required to price the record —
+ *                                      see scripts/lib/telemetry/pricing.mjs.
+ *   models_usage      array   | absent — per-model breakdown of a record whose token-
+ *                                      bearing turns used two or more models, every
+ *                                      one named (#1470): [{ model, token_input_uncached,
+ *                                      token_cache_read, token_cache_creation,
+ *                                      token_output }], one entry per model. The session
+ *                                      rollup prices each part; absent on every other record.
  *   total_cost_usd    number  | null — native total cost in USD (#624, fractional,
  *                                      best-effort: null when the harness does not
  *                                      expose it; no rate table is applied)
@@ -115,7 +123,8 @@ export class ValidationError extends Error {
  *
  * Required fields: timestamp, event, agent_id, schema_version.
  * Additional requirement when event='stop': duration_ms (integer or null).
- * Optional: agent_type, parent_session_id, token_input, token_output.
+ * Optional: agent_type, parent_session_id, token_input, token_output, the cache
+ * buckets, model, models_usage, total_cost_usd and the OTel aliases.
  *
  * @param {object} entry
  * @param {object} [options]
@@ -233,6 +242,24 @@ export function validateSubagent(entry, options = {}) {
     throw new ValidationError('model must be a string or null', 'model');
   }
 
+  // models_usage (optional, #1470) — per-model parts of a mixed-model record.
+  // Each part is priced on its own, so each needs a model and four buckets.
+  if (entry.models_usage !== undefined && entry.models_usage !== null) {
+    if (!Array.isArray(entry.models_usage)) {
+      throw new ValidationError('models_usage must be an array or null', 'models_usage');
+    }
+    for (const part of entry.models_usage) {
+      const bucketsValid = ['token_input_uncached', 'token_cache_read', 'token_cache_creation', 'token_output']
+        .every((field) => Number.isInteger(part?.[field]) && part[field] >= 0);
+      if (typeof part?.model !== 'string' || part.model.length === 0 || !bucketsValid) {
+        throw new ValidationError(
+          'models_usage entries must carry a model string and four non-negative integer token buckets',
+          'models_usage'
+        );
+      }
+    }
+  }
+
   // total_cost_usd (optional, #624) — fractional number (not integer), best-effort.
   if (entry.total_cost_usd !== undefined && entry.total_cost_usd !== null) {
     if (typeof entry.total_cost_usd !== 'number' || !Number.isFinite(entry.total_cost_usd) || entry.total_cost_usd < 0) {

package/scripts/lib/tail-window.mjs

@@ -0,0 +1,56 @@
+/**
+ * tail-window.mjs — the ONE bounded tail-window reader for append-only JSONL
+ * ledgers and transcripts (#1272).
+ *
+ * Five call sites used to carry their own copy of this byte-window primitive,
+ * and one of them (hooks/subagent-telemetry.mjs) ignored the returned read
+ * length and decoded a whole `allocUnsafe` buffer — on a short read that is
+ * uninitialised memory handed to JSON.parse. This module owns ONLY the byte
+ * window; every caller keeps its own error mapping (null / [] / discriminated
+ * result / throw) and its own line logic.
+ *
+ * Ceiling: the whole window is held in memory at once and decoded in one pass
+ * — fine for the windows in use today (64 KiB .. 1 MiB). Revisit if a caller
+ * needs a window above ~16 MiB: stream backwards in chunks instead.
+ */
+
+import fs from 'node:fs';
+
+/**
+ * Read the last `maxBytes` of `file` as UTF-8.
+ *
+ * `cut` is true when the window did not start at byte 0 — the first line of
+ * `text` is then (or may be) a fragment of a record, possibly starting inside
+ * a multi-byte UTF-8 sequence, and callers that parse lines should drop it.
+ * Loops until the window is filled or the file reports EOF, so a short read
+ * never leaves undecoded buffer bytes in `text`.
+ *
+ * THROWS on any fs error (ENOENT, EACCES, …) — mapping the failure is the
+ * caller's decision.
+ *
+ * @param {string} file
+ * @param {number} maxBytes  window size in bytes (> 0)
+ * @returns {{ text: string, cut: boolean, size: number }}  `size` is the file size at open time
+ */
+export function readTailWindow(file, maxBytes) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const want = Math.min(size, maxBytes);
+    const start = size - want;
+    const buf = Buffer.allocUnsafe(want);
+    let read = 0;
+    while (read < want) {
+      const n = fs.readSync(fd, buf, read, want - read, start + read);
+      if (n <= 0) break;
+      read += n;
+    }
+    return { text: buf.subarray(0, read).toString('utf8'), cut: start > 0, size };
+  } finally {
+    try {
+      fs.closeSync(fd);
+    } catch {
+      /* best-effort */
+    }
+  }
+}