session-orchestrator 4.1.0 → 4.2.0

package/scripts/lib/session-end/phase-skip.mjs

@@ -6,11 +6,23 @@
  * the close-out abort-attractor: six phases, each ~50 lines of coordinator prose,
  * that in the overwhelming majority of sessions do nothing (no proposals queued,
  * nothing expired, under cadence, judge off, reconcile off). This aggregator
- * computes — side-effect-free — WHICH of the six should actually run, so the
+ * computes — side-effect-free — WHICH of them should actually run, so the
  * coordinator loads only the detail procedure for the `run: true` phases and
  * emits a one-line `skippedReport` for the rest.
  *
- * Every one of the six phases already ships a mechanical fast-path in its own lib
+ * FOUR phases are still LIVE and decided here: 3.6.3, 3.6.4, 3.6.6, 3.6.8.
+ * TWO are RETIRED (2026-09-09) and always emit a `run: false` entry with
+ * `inputSource: 'retired'`: 3.6.5 Auto-Dream and 3.6.7 Auto-Dialectic. Both
+ * nudges are now computed once at SESSION-START by the `maintenance-due` probe
+ * (`scripts/lib/maintenance-due-banner.mjs`), which runs the same
+ * `shouldDispatchAutoDream` / `shouldDispatchAutoDialectic` signals and
+ * recommends `/session housekeeping`. Measured across three consumer repos the
+ * close-time nudges fired (`orchestrator.dialectic.nudge_decided`,
+ * `decided: true`, sessions_since 23/8/6) and were never acted on — computing
+ * them at every close was pure cost. The plan SHAPE is unchanged (still six
+ * entries, same ids, same order) so every reader keeps working.
+ *
+ * Each of the four live phases already ships a mechanical fast-path in its own lib
  * (a config kill-switch, an `existsSync` short-circuit, or a cadence/trigger
  * decision). This module WRAPS those existing signals — it never re-implements
  * their logic. Config gates run FIRST as the cheap short-circuit (no disk touch),
@@ -34,9 +46,10 @@
  * @property {boolean} run         - true → coordinator runs the detail procedure.
  * @property {string}  reason      - human-readable reason for the decision.
  * @property {string}  inputSource - which signal drove the decision
- *   ('config-gate' | 'proposals.jsonl' | 'sweep-dry-run' | 'auto-dream-signal' |
- *    'skill-invocations.jsonl' | 'auto-dialectic-signal' | 'reconcile-dry-run' |
- *    'learnings.jsonl' | 'probe-error').
+ *   ('config-gate' | 'proposals.jsonl' | 'sweep-dry-run' |
+ *    'skill-invocations.jsonl' | 'reconcile-dry-run' | 'learnings.jsonl' |
+ *    'retired' | 'probe-error'). `'retired'` is emitted only by the two
+ *    permanently-skipped phases 3.6.5 / 3.6.7 — no signal was consulted at all.
  * @property {string[]} [targets] - 3.6.8 only, RUN decisions only: the effective
  *   reconcile write-targets (issue #1099). Additive — absent on every other phase.
  * @property {string|null} [baselineRoot] - 3.6.8 only, RUN decisions only: the
@@ -52,11 +65,38 @@ import path from 'node:path';
 
 import { collectProposals } from '../memory-proposals/collector.mjs';
 import { sweepExpiredLearnings } from '../learnings/expiry-sweep.mjs';
-import { shouldDispatchAutoDream } from '../auto-dream.mjs';
-import { shouldDispatchAutoDialectic } from '../auto-dialectic.mjs';
 import { readSkillInvocations } from '../skill-invocations-schema.mjs';
 import { runReconcileFromPhaseSkip, resolveEffectiveTargets } from '../reconcile/engine.mjs';
-import { resolveMemoryDir } from '../memory-paths.mjs';
+
+// NOTE (2026-09-09): `shouldDispatchAutoDream` / `shouldDispatchAutoDialectic`
+// are deliberately NOT imported here any more — 3.6.5 and 3.6.7 are retired and
+// the two signals are computed once at session-start by the `maintenance-due`
+// probe. Re-adding either import is the regression this module's test suite
+// guards against.
+
+// ---------------------------------------------------------------------------
+// Shared path resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the learnings store + archive sidecar paths for a repo.
+ *
+ * Exported because `session-end/tail-runner.mjs` (the APPLY counterpart to the
+ * 3.6.4 dry-run decision below) must sweep exactly the pair this decision
+ * probed. Two hand-written `path.join(repoRoot, '.orchestrator', 'metrics', …)`
+ * recipes are one rename away from the planner deciding on one store while the
+ * runner rewrites another.
+ *
+ * @param {string} repoRoot
+ * @returns {{filePath: string, archivePath: string}}
+ */
+export function resolveLearningsPaths(repoRoot) {
+  const dir = path.join(repoRoot, '.orchestrator', 'metrics');
+  return {
+    filePath: path.join(dir, 'learnings.jsonl'),
+    archivePath: path.join(dir, 'learnings-archive.jsonl'),
+  };
+}
 
 // ---------------------------------------------------------------------------
 // Decision constructors
@@ -92,6 +132,23 @@ function mkProbeError(phase, err) {
   return decision(phase, true, `probe-error: ${msg}`, 'probe-error');
 }
 
+/** Phase ids retired on 2026-09-09 — kept in the plan, never decided. */
+const RETIRED_PHASES = new Set(['3.6.5', '3.6.7']);
+
+/** The reason string every retired phase carries, verbatim. */
+const RETIRED_REASON = 'retired 2026-09-09 — replaced by session-start maintenance-due probe';
+
+/**
+ * Permanent skip for a retired phase. No signal is read and no config key is
+ * consulted — not even a kill-switch, because there is nothing left to switch.
+ *
+ * @param {string} phase
+ * @returns {PhaseDecision}
+ */
+function mkRetired(phase) {
+  return mkSkip(phase, RETIRED_REASON, 'retired');
+}
+
 // ---------------------------------------------------------------------------
 // Config / platform helpers
 // ---------------------------------------------------------------------------
@@ -101,17 +158,6 @@ function isPersistenceOff(cfg) {
   return cfg && cfg.persistence === false;
 }
 
-/**
- * MEMORY.md (Auto-Dream signal source) lives under `~/.claude/projects/` — a
- * Claude Code-only path. Absent platform → treated as Claude Code (the common
- * coordinator context); any explicit non-Claude platform gates 3.6.5 off.
- */
-function isClaudePlatform(platform) {
-  if (platform === undefined || platform === null || platform === '') return true;
-  const p = String(platform).toLowerCase();
-  return p === 'claude' || p === 'claude-code' || p === 'claudecode';
-}
-
 // ---------------------------------------------------------------------------
 // Per-phase deciders — each wraps an EXISTING signal helper, config-gate first.
 // ---------------------------------------------------------------------------
@@ -149,14 +195,8 @@ async function decideMemoryProposals({ repoRoot, cfg }) {
 async function decideExpiredSweep({ repoRoot }) {
   const phase = '3.6.4';
   try {
-    const filePath = path.join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
+    const { filePath, archivePath } = resolveLearningsPaths(repoRoot);
     if (!existsSync(filePath)) return mkSkip(phase, 'learnings.jsonl absent', 'learnings.jsonl');
-    const archivePath = path.join(
-      repoRoot,
-      '.orchestrator',
-      'metrics',
-      'learnings-archive.jsonl',
-    );
     const res = await sweepExpiredLearnings({ filePath, archivePath, dryRun: true });
     if (!res || res.archived === 0) {
       return mkSkip(phase, `nothing archive-eligible (scanned=${res?.scanned ?? 0})`, 'sweep-dry-run');
@@ -168,36 +208,6 @@ async function decideExpiredSweep({ repoRoot }) {
   }
 }
 
-/**
- * 3.6.5 Auto-Dream nudge (#502). Config gate (kill-switch threshold=0, platform)
- * → then `shouldDispatchAutoDream` (trigger:false branches → skip).
- */
-async function decideAutoDream({ repoRoot, cfg, platform, memoryDir }) {
-  const phase = '3.6.5';
-  try {
-    const threshold = cfg?.['memory-cleanup-threshold'] ?? 5;
-    if (threshold === 0) {
-      return mkSkip(phase, 'kill-switch (memory-cleanup-threshold=0)', 'config-gate');
-    }
-    if (!isClaudePlatform(platform)) {
-      return mkSkip(phase, 'non-Claude-Code platform (memory dir unavailable)', 'config-gate');
-    }
-    // #1071: same root as the `repoRoot` handed to shouldDispatchAutoDream below —
-    // a cwd-derived memory dir made the two halves of this decision disagree.
-    const dir = memoryDir ?? resolveMemoryDir(repoRoot);
-    const dec = await shouldDispatchAutoDream({
-      repoRoot,
-      memoryDir: dir,
-      threshold,
-      softLimit: cfg?.['memory-cleanup-soft-limit'] ?? 180,
-    });
-    if (!dec.trigger) return mkSkip(phase, dec.reason, 'auto-dream-signal');
-    return mkRun(phase, dec.reason, 'auto-dream-signal');
-  } catch (err) {
-    return mkProbeError(phase, err);
-  }
-}
-
 /**
  * 3.6.6 Skill-Applied Judge (#645 L3). Config gate (judge default OFF,
  * persistence) → then the judged-set emptiness check via
@@ -240,25 +250,6 @@ async function decideSkillJudge({ repoRoot, cfg, sessionId }) {
   }
 }
 
-/**
- * 3.6.7 Auto-Dialectic nudge (#506). Config gate (persistence, kill-switch
- * cadence=0) → then `shouldDispatchAutoDialectic` (the reference implementation
- * of the no-new-input-since-last-run pattern via `.orchestrator/dialectic-last-run`).
- */
-async function decideAutoDialectic({ repoRoot, cfg }) {
-  const phase = '3.6.7';
-  try {
-    if (isPersistenceOff(cfg)) return mkSkip(phase, 'persistence=false', 'config-gate');
-    const cadence = cfg?.dialectic?.cadence ?? 5;
-    if (cadence === 0) return mkSkip(phase, 'kill-switch (dialectic.cadence=0)', 'config-gate');
-    const dec = await shouldDispatchAutoDialectic({ repoRoot, cadence });
-    if (!dec.trigger) return mkSkip(phase, dec.reason, 'auto-dialectic-signal');
-    return mkRun(phase, dec.reason, 'auto-dialectic-signal');
-  } catch (err) {
-    return mkProbeError(phase, err);
-  }
-}
-
 /**
  * 3.6.8 Reconciliation Rule Proposals (#696). Config gate (persistence,
  * reconcile.enabled default OFF, learnings.jsonl present) → then `runReconcile`
@@ -354,37 +345,45 @@ export function buildSkippedReport(plan) {
 // ---------------------------------------------------------------------------
 
 /**
- * Compute the run/skip plan for the six session-end Phase 3.6.x tail phases.
+ * Compute the run/skip plan for the six session-end Phase 3.6.x tail phase ids
+ * — four decided from live signals, two permanently retired (see the module
+ * header). The plan keeps all six entries, in id order, so readers that index
+ * by phase id are unaffected by the retirement.
  *
- * NEVER throws — each phase probe fail-opens to `run: true`, and the top-level
- * guard converts any unexpected error into an all-run plan so the coordinator
- * runs the full tail rather than silently skipping it.
+ * NEVER throws — each live phase probe fail-opens to `run: true`, and the
+ * top-level guard converts any unexpected error into an all-run plan so the
+ * coordinator runs the full tail rather than silently skipping it. The two
+ * retired phases stay `run: false` even on that error path: fail-open exists to
+ * avoid LOSING a phase, and a retired phase has no procedure left to lose.
  *
  * @param {object} args
  * @param {string}  args.repoRoot   Absolute repo root.
  * @param {object}  args.config     Parsed Session Config object (from parse-config.mjs).
  * @param {string|null} [args.sessionId] Current session id (for the 3.6.6 judged-set filter).
- * @param {string}  [args.platform] Platform id ('claude' | 'codex' | 'cursor' | …).
- * @param {string}  [args.memoryDir] Optional Auto-Dream memory dir override (default resolveMemoryDir(repoRoot)).
+ * @param {string}  [args.platform] ACCEPTED AND IGNORED since the 3.6.5 retirement
+ *   (2026-09-09) — the platform gate existed only for the Auto-Dream memory dir.
+ *   Kept in the signature because live callers still pass it.
+ * @param {string}  [args.memoryDir] ACCEPTED AND IGNORED, same reason as `platform`.
  * @returns {Promise<TailPlan>}
  */
-export async function planTailPhases({ repoRoot, config, sessionId, platform, memoryDir } = {}) {
+export async function planTailPhases({ repoRoot, config, sessionId } = {}) {
   const cfg = config ?? {};
   try {
     const plan = await Promise.all([
       decideMemoryProposals({ repoRoot, cfg }),
       decideExpiredSweep({ repoRoot }),
-      decideAutoDream({ repoRoot, cfg, platform, memoryDir }),
+      mkRetired('3.6.5'),
       decideSkillJudge({ repoRoot, cfg, sessionId }),
-      decideAutoDialectic({ repoRoot, cfg }),
+      mkRetired('3.6.7'),
       decideReconcile({ repoRoot, cfg }),
     ]);
     return { plan, skippedReport: buildSkippedReport(plan) };
   } catch (err) {
-    // Top-level fail-open guard: run the full tail rather than lose it silently.
+    // Top-level fail-open guard: run the full LIVE tail rather than lose it
+    // silently. Retired phases are never resurrected by an error.
     const msg = err && err.message ? err.message : String(err);
     const plan = ['3.6.3', '3.6.4', '3.6.5', '3.6.6', '3.6.7', '3.6.8'].map((p) =>
-      decision(p, true, `probe-error: ${msg}`, 'probe-error'),
+      RETIRED_PHASES.has(p) ? mkRetired(p) : decision(p, true, `probe-error: ${msg}`, 'probe-error'),
     );
     return { plan, skippedReport: buildSkippedReport(plan) };
   }

package/scripts/lib/session-end/tail-runner.mjs

@@ -0,0 +1,178 @@
+/**
+ * session-end/tail-runner.mjs — the APPLY half of the Phase 3.6.x tail.
+ *
+ * `phase-skip.mjs` decides WHICH tail phases should run and is side-effect-free
+ * by contract. Until now nothing was the other half for 3.6.4: the
+ * Expired-Learnings Sweep was coordinator PROSE, so the dry-run decision was
+ * computed on every close and the apply path was never mechanically reached.
+ * Census (2026-09-09, `rg -n sweepExpiredLearnings scripts/ hooks/ skills/
+ * tests/`): the only call sites were the definition itself, the `dryRun: true`
+ * probe in `phase-skip.mjs`, the standalone CLI, and tests — no session-end
+ * caller applied anything. Measured consequence across three consumer repos:
+ * 0 sweeps ever applied, 628 learnings resident in the active stores.
+ *
+ * This module closes that gap and nothing else. It is deliberately NOT a
+ * general tail executor:
+ *
+ *   - **3.6.3 Memory-Proposals** — AUQ-gated (the operator approves each
+ *     proposal before it is written); `.claude/rules/ask-via-tool.md` AUQ-004
+ *     puts the tool out of reach of anything but the coordinator thread.
+ *   - **3.6.5 Auto-Dream** and **3.6.7 Auto-Dialectic** — both NUDGES that end
+ *     in a subagent dispatch (memory-cleanup, `dialectic-deriver`); a library
+ *     function cannot dispatch an agent.
+ *   - **3.6.6 Skill-Judge** — needs a live LLM dispatch for the judgement.
+ *   - **3.6.8 Reconcile** — the write is operator-approved per proposal (AUQ),
+ *     which is the whole never-always-on firewall of Epic #693.
+ *
+ * So {@link runTailPhases} exists as the SEAM (one dispatch table, one result
+ * shape) rather than as an abstraction over six phases that will never all be
+ * mechanical. A future phase that becomes mechanical is added here; the five
+ * above stay coordinator-executed by design, not by omission.
+ *
+ * Never-throws contract, and its DIRECTION is the opposite of `phase-skip.mjs`.
+ * The planner fails OPEN (probe error → run the phase, because losing a phase
+ * silently is worse than running it needlessly). A runner that writes to disk
+ * must fail CLOSED: any error yields `{ran: false, reason: 'error'}` and the
+ * close proceeds. Session close is the one thing that must never be blocked by
+ * a best-effort maintenance sweep — a store that stays unswept for one more
+ * session costs nothing; a close that aborts loses the session record.
+ *
+ * Plain Node ESM, no external deps.
+ *
+ * @typedef {Object} SweepResult
+ * @property {boolean} ran            - true only when the store was actually rewritten.
+ * @property {string}  [reason]       - why it did not run ('plan-skip' | 'no-plan' | 'error').
+ * @property {string}  [error]        - error message, `reason === 'error'` only.
+ * @property {number}  [scanned]      - entries read from the active store (ran only).
+ * @property {number}  [archived]     - entries moved to the archive sidecar (ran only).
+ * @property {string}  [archivePath]  - the archive sidecar written to (ran only).
+ */
+
+import { sweepExpiredLearnings } from '../learnings/expiry-sweep.mjs';
+import { resolveLearningsPaths } from './phase-skip.mjs';
+
+/** Event name — a plain string literal so the events-schema census can see it. */
+const SWEEP_EVENT = 'orchestrator.learnings.sweep_applied';
+
+/** Payload marker for the producer, so the ledger separates it from the CLI. */
+const SWEEP_SOURCE = 'session-end-3.6.4';
+
+/**
+ * Pull the decision for one phase id out of a `planTailPhases()` result.
+ *
+ * Accepts three shapes so callers need no adapter: the full
+ * `{plan, skippedReport}` envelope, a bare `PhaseDecision[]`, or a single
+ * `PhaseDecision` object. Anything else → `null` (treated as "no plan").
+ *
+ * @param {object|Array|undefined} plan
+ * @param {string} phase
+ * @returns {object|null}
+ */
+function findPhaseDecision(plan, phase) {
+  if (!plan) return null;
+  const list = Array.isArray(plan) ? plan : Array.isArray(plan.plan) ? plan.plan : null;
+  if (list) return list.find((d) => d && d.phase === phase) ?? null;
+  return plan.phase === phase ? plan : null;
+}
+
+/**
+ * Emit the one sweep record. Best-effort by construction: a telemetry failure
+ * never changes the caller's return value.
+ *
+ * The shape (lazy `events.mjs` import, explicit `repoRoot`, silent catch) is
+ * copied from `_emitEvaluated` in `scripts/lib/express-path.mjs`. Both halves
+ * are load-bearing: the lazy import keeps `platform.mjs`'s load-time filesystem
+ * walk-up out of the static graph of a module the planner imports, and the
+ * refusal to emit WITHOUT an explicit `repoRoot` prevents the `SO_PROJECT_DIR`
+ * fallback from writing a synthetic record into whatever tree the ambient env
+ * happens to resolve to (#941 — that mistake once landed a test record in the
+ * operator's real fleet ledger).
+ *
+ * @param {{repoRoot: string, scanned: number, archived: number}} ctx
+ * @returns {Promise<void>}
+ */
+async function emitSweepApplied({ repoRoot, scanned, archived }) {
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') {
+    process.stderr.write(
+      `tail-runner: skipped ${SWEEP_EVENT} — no repoRoot given; ` +
+        'refusing the ambient SO_PROJECT_DIR destination (#941).\n',
+    );
+    return;
+  }
+  try {
+    const { emitEvent, sessionAttribution } = await import('../events.mjs');
+    await emitEvent(
+      SWEEP_EVENT,
+      { scanned, archived, source: SWEEP_SOURCE, ...sessionAttribution(repoRoot) },
+      { repoRoot },
+    );
+  } catch {
+    // Best-effort telemetry — the sweep already happened and its result is
+    // authoritative whether or not the ledger accepted the record.
+  }
+}
+
+/**
+ * Phase 3.6.4 — apply the Expired-Learnings Sweep the planner decided on.
+ *
+ * Runs ONLY when the plan's 3.6.4 decision says `run === true`. Any other
+ * shape (skip decision, phase absent, no plan at all) returns without touching
+ * disk — the planner owns the decision, this function owns the write, and a
+ * runner that re-derives the decision would be free to disagree with it.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot            Absolute repo root.
+ * @param {object|Array} [args.plan]        `planTailPhases()` result, its `plan`
+ *                                          array, or the bare 3.6.4 decision.
+ * @param {Date|number} [args.now]          Injectable clock (grace-window maths).
+ * @param {number} [args.graceDays]         Override the 14-day grace window.
+ * @param {boolean} [args.emit=true]        Set false to suppress the ledger record.
+ * @returns {Promise<SweepResult>}          Never throws.
+ */
+export async function runExpiredSweep({ repoRoot, plan, now, graceDays, emit = true } = {}) {
+  try {
+    const decision = findPhaseDecision(plan, '3.6.4');
+    if (!decision) return { ran: false, reason: 'no-plan' };
+    if (decision.run !== true) {
+      return { ran: false, reason: 'plan-skip', planReason: decision.reason };
+    }
+    if (typeof repoRoot !== 'string' || repoRoot.trim() === '') {
+      return { ran: false, reason: 'error', error: 'runExpiredSweep: repoRoot is required' };
+    }
+
+    const { filePath, archivePath } = resolveLearningsPaths(repoRoot);
+    const res = await sweepExpiredLearnings({
+      filePath,
+      archivePath,
+      now,
+      dryRun: false,
+      ...(graceDays === undefined ? {} : { graceDays }),
+    });
+
+    const scanned = res?.scanned ?? 0;
+    const archived = res?.archived ?? 0;
+    if (emit) await emitSweepApplied({ repoRoot, scanned, archived });
+
+    return { ran: true, scanned, archived, archivePath: res?.archivePath ?? archivePath };
+  } catch (err) {
+    // Fail CLOSED (see the module header): a maintenance sweep must never be
+    // able to block a session close.
+    return { ran: false, reason: 'error', error: err && err.message ? err.message : String(err) };
+  }
+}
+
+/**
+ * Run every MECHANICAL phase of the session-end tail.
+ *
+ * Today that is exactly one — 3.6.4. See the module header for why 3.6.3 and
+ * 3.6.5–3.6.8 stay coordinator-executed (AUQ-gated per
+ * `.claude/rules/ask-via-tool.md` AUQ-004, or requiring a subagent dispatch a
+ * library function cannot make). The keyed return shape is the seam: a caller
+ * reads `result['3.6.4']` today and keeps compiling when a second phase lands.
+ *
+ * @param {object} args — forwarded verbatim to {@link runExpiredSweep}.
+ * @returns {Promise<Record<string, SweepResult>>} Never throws.
+ */
+export async function runTailPhases({ repoRoot, plan, now, graceDays, emit } = {}) {
+  return { '3.6.4': await runExpiredSweep({ repoRoot, plan, now, graceDays, emit }) };
+}

package/scripts/lib/session-schema/constants.mjs

@@ -161,6 +161,12 @@ export const OPTIONAL_FIELDS = Object.freeze([
   'total_token_input',
   'total_token_output',
   'subagents_with_tokens',
+  // #1244 — cache buckets + cost estimate (additive, optional).
+  'total_token_input_uncached',
+  'total_token_cache_read',
+  'total_token_cache_creation',
+  'total_cost_usd',
+  '_token_schema',
   // Epic #724 C1 — SessionEnd close-through backfill provenance fields.
   // `status` distinguishes normally-closed ('completed') from hook-backfilled
   // ('abandoned') records. The `_backfill_*` markers record how a stub was

package/scripts/lib/session-schema/validator.mjs

@@ -384,6 +384,26 @@ function _validateOptionalFields(entry) {
       );
     }
   }
+  // #1244 — cache buckets, cost estimate and the token-contract marker.
+  // Same non-negative-finite-or-null contract as the two totals above;
+  // total_cost_usd is fractional and null means "unknown model", never 0.
+  for (const field of [
+    'total_token_input_uncached',
+    'total_token_cache_read',
+    'total_token_cache_creation',
+    'total_cost_usd',
+    '_token_schema',
+  ]) {
+    const value = entry[field];
+    if (value !== undefined && value !== null) {
+      if (!Number.isFinite(value) || value < 0) {
+        throw new ValidationError(
+          `${field} must be a non-negative finite number or null, got: ${value}`
+        );
+      }
+    }
+  }
+
   // subagents_with_tokens: non-negative integer (never null — it is always a count, defaulting to 0).
   if (entry.subagents_with_tokens !== undefined && entry.subagents_with_tokens !== null) {
     if (