session-orchestrator 3.16.0

package/scripts/lib/session-discovery.mjs

@@ -0,0 +1,256 @@
+/**
+ * session-discovery.mjs — discover active sessions across all worktrees.
+ *
+ * Purpose: enumerate all active Claude sessions in the repo's worktree set
+ * (P1.1 of the Parallel-Aware Sessions Epic #568, Issue #569).
+ *
+ * Liveness rule (Epic #583, W2-I3 — REPLACES PID-liveness):
+ *   - A lock is "live" when (now - last_heartbeat) < ttl_hours.
+ *   - PID-liveness is no longer the discovery-time filter; the writer-process
+ *     PID is the *hook* PID, not the session PID, so PID-liveness incorrectly
+ *     filtered out locks whose semantic owner (Claude harness) was still
+ *     alive (D2 defect from Epic #583 audit).
+ *   - `isPidAliveOnHost` is preserved in session-lock.mjs as a forensic helper
+ *     but is not called from the discovery decision tree.
+ *   - #799 evaluated (2026-07-17): dead-PID stale-marking for source=discovered
+ *     registry entries is an explicit NO-GO — the recorded PID is the ephemeral
+ *     hook-subprocess PID (see above), so a same-host dead-PID filter would
+ *     misclassify nearly every entry as stale seconds after write; even a
+ *     corroborating PID *label* adds zero detection power over heartbeat
+ *     freshness (it could only ever annotate entries the heartbeat gate has
+ *     already excluded). Do not re-attempt without new evidence.
+ *
+ * Cross-host policy:
+ *   - Same-host: heartbeat freshness rules.
+ *   - Cross-host: heartbeat freshness rules (PID-liveness was already skipped
+ *     across hosts; nothing changes here).
+ *
+ * Registry fallback (Epic #583, W2-I3 — Merged Source-of-Truth):
+ *   - When a worktree's lock is null OR not live, the discovery path consults
+ *     the host registry as a fallback. Entries matching the current repo's
+ *     `repo_path_hash` and within `freshnessMin` are merged into the result.
+ *   - Lock takes precedence over registry (more detail per session); registry
+ *     supplements missing per-worktree entries (e.g., when the hook ran but
+ *     the prose Phase 1.2 acquire was skipped).
+ *
+ * Timeout + A1 fallback:
+ *   - listWorktrees() is raced against DEFAULT_DISCOVERY_TIMEOUT_MS (2 s).
+ *   - On timeout or throw → falls back to reading only the local session.lock.
+ *   - Timer uses .unref() so it never keeps the Node event loop alive.
+ *   - Stderr WARN: `[session-discovery] WARN: <reason> — falling back to single-worktree mode`
+ *
+ * DI hooks (for tests): opts.listWorktreesImpl, opts.timeoutMs, opts.registryReader.
+ */
+
+import os from 'node:os';
+import { listWorktrees } from './worktree/listing.mjs';
+import { readLock, isLockLive } from './session-lock.mjs';
+import { readRegistry, repoPathHash, isRegistryEntryFresh } from './session-registry.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default timeout in milliseconds for the listWorktrees race. */
+export const DEFAULT_DISCOVERY_TIMEOUT_MS = 2000;
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a lock object + worktree path/branch into the session-shape that
+ * discoverActiveSessions returns. Centralised so the in-tree + fallback paths
+ * emit identical shapes.
+ *
+ * @param {object} lock          Parsed lock body (schema v2).
+ * @param {string} worktreePath  Absolute worktree path.
+ * @param {string} [branch]      Branch from worktree object (falsy → '').
+ * @returns {{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,branch:string}}
+ */
+function sessionFromLock(lock, worktreePath, branch = '') {
+  return {
+    worktreePath,
+    sessionId:    lock.session_id,
+    mode:         lock.mode,
+    startedAt:    lock.started_at,
+    pid:          lock.pid,
+    host:         lock.host,
+    branch:       typeof branch === 'string' ? branch : '',
+  };
+}
+
+/**
+ * Convert a registry entry into the same session-shape. `worktreePath` is set
+ * to the repoRoot under which the discovery is running, since the registry
+ * does not record per-worktree paths — only repo-path-hashes. Branch is
+ * passed through from the registry entry when available.
+ *
+ * @param {object} entry    Registry entry.
+ * @param {string} repoRoot Discovery repoRoot (used as worktreePath fallback).
+ */
+function sessionFromRegistryEntry(entry, repoRoot) {
+  return {
+    worktreePath: repoRoot,
+    sessionId:    entry.session_id,
+    mode:         typeof entry.mode === 'string' ? entry.mode : 'session',
+    startedAt:    entry.started_at,
+    pid:          typeof entry.pid === 'number' ? entry.pid : 0,
+    // Registry entries do not currently record `host` (hostname); use the
+    // local hostname as the default since registry entries are host-scoped
+    // by design (see ~/.config/session-orchestrator/sessions/).
+    host:         os.hostname(),
+    branch:       typeof entry.branch === 'string' ? entry.branch : '',
+  };
+}
+
+/**
+ * A1 fallback — read only the local repoRoot's session.lock (0-or-1 result).
+ * `branch` is left empty; callers treat it as "unknown — A1 fallback active".
+ *
+ * Liveness rule: heartbeat freshness via isLockLive (Epic #583, W2-I3).
+ *
+ * @param {string} repoRoot
+ * @returns {Array<{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,branch:string}>}
+ */
+function readLocalSession(repoRoot) {
+  const lock = readLock({ repoRoot });
+  if (lock === null) return [];
+  if (!isLockLive(lock)) return [];
+  return [sessionFromLock(lock, repoRoot, '')];
+}
+
+/**
+ * Deduplicate a session list by sessionId, preferring earlier entries. The
+ * discovery path constructs the result with lock-sourced entries first
+ * (which carry more detail — exact worktreePath, branch from git) and
+ * appends registry-sourced entries; this dedupe keeps the lock-sourced one.
+ *
+ * @param {Array<{sessionId:string}>} sessions
+ * @returns {Array<{sessionId:string}>}
+ */
+function dedupeBySessionId(sessions) {
+  const seen = new Set();
+  const out = [];
+  for (const s of sessions) {
+    if (seen.has(s.sessionId)) continue;
+    seen.add(s.sessionId);
+    out.push(s);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// discoverActiveSessions
+// ---------------------------------------------------------------------------
+
+/**
+ * Discover all active sessions across the repository's worktree set.
+ *
+ * Liveness rule (Epic #583, W2-I3): heartbeat-based — `isLockLive(lock)`
+ * returns true when `(now - last_heartbeat) < ttl_hours`. Replaces the
+ * previous PID-liveness rule which incorrectly filtered out locks whose
+ * writer-process (hook PID) had exited.
+ *
+ * Registry fallback: after iterating worktree locks, registry entries with
+ * matching `repo_path_hash` that pass `isRegistryEntryFresh()` are merged
+ * into the result. Lock entries take precedence (they carry per-worktree
+ * detail); registry entries supplement when locks are absent or stale.
+ *
+ * On listWorktrees() failure or timeout, falls back to A1 single-worktree
+ * mode and emits a WARN to stderr.
+ *
+ * @param {string} repoRoot  Absolute path to the main repository root.
+ * @param {object} [opts]
+ * @param {number}   [opts.timeoutMs=2000]      Race timeout (ms). Default DEFAULT_DISCOVERY_TIMEOUT_MS.
+ * @param {Function} [opts.listWorktreesImpl]   DI hook replacing listWorktrees() for tests.
+ * @param {Function} [opts.registryReader]      DI hook replacing readRegistry() for tests.
+ * @param {number}   [opts.freshnessMin=15]     Registry-entry freshness threshold in minutes.
+ * @param {number}   [opts.now]                 ms-since-epoch (test seam for heartbeat freshness).
+ * @returns {Promise<Array<{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,branch:string}>>}
+ */
+export async function discoverActiveSessions(repoRoot, opts = {}) {
+  const listWorktreesFn = opts.listWorktreesImpl ?? listWorktrees;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_DISCOVERY_TIMEOUT_MS;
+  const registryReaderFn = opts.registryReader ?? readRegistry;
+  const freshnessMin = typeof opts.freshnessMin === 'number' ? opts.freshnessMin : 15;
+  const nowMs = typeof opts.now === 'number' ? opts.now : Date.now();
+
+  let worktrees;
+  try {
+    worktrees = await Promise.race([
+      listWorktreesFn(),
+      new Promise((_, reject) => {
+        const timer = setTimeout(() => reject(new Error('timeout')), timeoutMs);
+        timer.unref();
+      }),
+    ]);
+  } catch (err) {
+    // Either listWorktrees threw, or our timeout fired. Either way: A1 fallback.
+    const reason = err.message === 'timeout'
+      ? `git worktree list timed out at ${timeoutMs}ms`
+      : `git worktree list failed: ${err.message}`;
+    process.stderr.write(`[session-discovery] WARN: ${reason} — falling back to single-worktree mode\n`);
+    return readLocalSession(repoRoot);
+  }
+
+  const lockSessions = [];
+
+  for (const worktree of worktrees) {
+    // Read the lock for this worktree (returns null if absent or malformed).
+    const lock = readLock({ repoRoot: worktree.path });
+
+    // No lock → no session in this worktree (registry fallback handled below).
+    if (lock === null) {
+      continue;
+    }
+
+    // Liveness rule (Epic #583, W2-I3): heartbeat freshness, not PID-liveness.
+    if (!isLockLive(lock, nowMs)) {
+      // Stale by heartbeat — exclude. (Registry fallback may still recover the
+      // session id if the registry entry is fresh.)
+      continue;
+    }
+
+    lockSessions.push(sessionFromLock(lock, worktree.path, worktree.branch));
+  }
+
+  // Registry fallback (Merged Source-of-Truth, Epic #583, W2-I3).
+  // Filter to entries that (a) match this repo's repo_path_hash and (b) pass
+  // the freshness gate. Failures are swallowed — registry is advisory.
+  let registrySessions;
+  try {
+    const allEntries = await registryReaderFn();
+    const myRepoHash = repoPathHash(repoRoot);
+    registrySessions = allEntries
+      .filter((e) => e && e.repo_path_hash === myRepoHash)
+      .filter((e) => isRegistryEntryFresh(e, { freshnessMin, now: nowMs }))
+      .map((e) => sessionFromRegistryEntry(e, repoRoot));
+  } catch {
+    // Registry read failure → keep going with lock-only results.
+    registrySessions = [];
+  }
+
+  // Merge: lock-sourced first (more detail), then registry. Dedupe by
+  // sessionId so a session that has both a lock and a registry entry only
+  // appears once with the richer lock detail.
+  return dedupeBySessionId([...lockSessions, ...registrySessions]);
+}
+
+// ---------------------------------------------------------------------------
+// findWorktrees
+// ---------------------------------------------------------------------------
+
+/**
+ * Thin namespace-cohesion wrapper around listWorktrees().
+ *
+ * The `repoRoot` parameter is reserved for future per-worktree filtering
+ * (Issue #569 P1.2) and is currently passed through without effect.
+ *
+ * @param {string} _repoRoot  Absolute path to the main repository root (reserved).
+ * @returns {Promise<Array<{path: string, branch: string, head: string}>>}
+ *   Same shape as listWorktrees(); empty array on git failure.
+ */
+export async function findWorktrees(_repoRoot) {
+  return listWorktrees();
+}

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

@@ -0,0 +1,357 @@
+/**
+ * session-end/phase-skip.mjs — Tail-Diät skip-plan aggregator (Issue #724).
+ *
+ * The session-end Phase 3.6.x tail (3.6.3 Memory-Proposals, 3.6.4 Expired-Sweep,
+ * 3.6.5 Auto-Dream, 3.6.6 Skill-Judge, 3.6.7 Auto-Dialectic, 3.6.8 Reconcile) is
+ * 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
+ * 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
+ * (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),
+ * then the input-detection helpers run only when the config gate passed.
+ *
+ * Side-effect-free contract:
+ *   - reads only (existsSync / read helpers); writes NOTHING.
+ *   - reconcile runs with `dryRun: true` so the candidate sidecar is never written.
+ *   - the sweep runs with `dryRun: true` (its default) so the store is untouched.
+ *
+ * Never-throws contract (mirrors the banner-probe posture): a failure while
+ * probing a single phase degrades to `run: true` (fail-open) with a
+ * `probe-error: …` reason — when in doubt, RUN the phase rather than silently
+ * lose it. `planTailPhases` itself never throws to its caller.
+ *
+ * Plain Node ESM, no external deps — Node 20+ stdlib + the six read-only signal
+ * helpers only.
+ *
+ * @typedef {Object} PhaseDecision
+ * @property {string}  phase       - the phase id, e.g. '3.6.3'.
+ * @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').
+ *
+ * @typedef {Object} TailPlan
+ * @property {PhaseDecision[]} plan
+ * @property {string} skippedReport
+ */
+
+import { existsSync } from 'node:fs';
+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 { runReconcile } from '../reconcile/engine.mjs';
+import { resolveMemoryDir } from '../memory-paths.mjs';
+
+// ---------------------------------------------------------------------------
+// Decision constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} phase
+ * @param {boolean} run
+ * @param {string} reason
+ * @param {string} inputSource
+ * @returns {PhaseDecision}
+ */
+function decision(phase, run, reason, inputSource) {
+  return { phase, run, reason, inputSource };
+}
+
+/** Skip decision. */
+function mkSkip(phase, reason, inputSource) {
+  return decision(phase, false, reason, inputSource);
+}
+
+/** Run decision. */
+function mkRun(phase, reason, inputSource) {
+  return decision(phase, true, reason, inputSource);
+}
+
+/**
+ * Fail-open decision for a probe that threw. Runs the phase (never silently
+ * loses it) and stamps a `probe-error: …` reason.
+ */
+function mkProbeError(phase, err) {
+  const msg = err && err.message ? err.message : String(err);
+  return decision(phase, true, `probe-error: ${msg}`, 'probe-error');
+}
+
+// ---------------------------------------------------------------------------
+// Config / platform helpers
+// ---------------------------------------------------------------------------
+
+/** persistence is off only when explicitly `false`; absent → treated as on. */
+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.
+// ---------------------------------------------------------------------------
+
+/**
+ * 3.6.3 Memory-Proposals Collection (#501). Config gate (persistence,
+ * memory.proposals.enabled) → then `collectProposals` (existsSync short-circuit
+ * on proposals.jsonl → empty queue).
+ */
+async function decideMemoryProposals({ repoRoot, cfg }) {
+  const phase = '3.6.3';
+  try {
+    if (isPersistenceOff(cfg)) return mkSkip(phase, 'persistence=false', 'config-gate');
+    if (cfg?.memory?.proposals?.enabled === false) {
+      return mkSkip(phase, 'memory.proposals.enabled=false', 'config-gate');
+    }
+    const { queue, stats } = await collectProposals({
+      repoRoot,
+      minConfidence: cfg?.['auto-dream']?.['min-confidence'],
+    });
+    if (!Array.isArray(queue) || queue.length === 0) {
+      return mkSkip(phase, `proposals empty (queued=${stats?.queued ?? 0})`, 'proposals.jsonl');
+    }
+    return mkRun(phase, `${queue.length} proposal(s) queued`, 'proposals.jsonl');
+  } catch (err) {
+    return mkProbeError(phase, err);
+  }
+}
+
+/**
+ * 3.6.4 Expired-Learnings Sweep (Epic #723 B4). No config gate — best-effort,
+ * non-blocking. `sweepExpiredLearnings` runs in `dryRun: true` (writes nothing):
+ * archived === 0 → nothing to move → skip.
+ */
+async function decideExpiredSweep({ repoRoot }) {
+  const phase = '3.6.4';
+  try {
+    const filePath = path.join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
+    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');
+    }
+    const plural = res.archived === 1 ? 'y' : 'ies';
+    return mkRun(phase, `${res.archived} entr${plural} archive-eligible`, 'sweep-dry-run');
+  } catch (err) {
+    return mkProbeError(phase, err);
+  }
+}
+
+/**
+ * 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');
+    }
+    const dir = memoryDir ?? resolveMemoryDir();
+    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
+ * `readSkillInvocations` (mirrors runSkillJudge's `empty-input` gate: no
+ * selected skill this session → nothing to judge → skip). This computes the
+ * judged set the coordinator would compute anyway; it does NOT re-implement the
+ * judge (runSkillJudge needs a live dispatch, which is not side-effect-free).
+ *
+ * `sessionId === null/undefined` (noSessionFilter) deliberately falls to the
+ * BROADER match — every entry in skill-invocations.jsonl counts toward
+ * `judged`, regardless of which session recorded it. This can over-count (a
+ * `run: true` decision when the true current-session set would have been
+ * empty), which is the fail-open direction: worst case the coordinator loads
+ * the 3.6.6 detail procedure for nothing, since the REAL `runSkillJudge` self-
+ * gates on its own empty-input check when it actually runs. It never
+ * under-counts into a false skip.
+ */
+async function decideSkillJudge({ repoRoot, cfg, sessionId }) {
+  const phase = '3.6.6';
+  try {
+    if (cfg?.['skill-evolution']?.judge !== true) {
+      return mkSkip(phase, 'disabled (skill-evolution.judge=false)', 'config-gate');
+    }
+    if (isPersistenceOff(cfg)) return mkSkip(phase, 'persistence=false', 'config-gate');
+    const invPath = path.join(repoRoot, '.orchestrator', 'metrics', 'skill-invocations.jsonl');
+    const entries = await readSkillInvocations(invPath);
+    const noSessionFilter = sessionId === null || sessionId === undefined;
+    const judged = new Set(
+      entries
+        .filter((e) => noSessionFilter || e.session_id === sessionId)
+        .map((e) => e.skill)
+        .filter((s) => typeof s === 'string' && s.trim().length > 0),
+    );
+    if (judged.size === 0) {
+      return mkSkip(phase, 'empty-input (no selected skills this session)', 'skill-invocations.jsonl');
+    }
+    return mkRun(phase, `${judged.size} selected skill(s) to judge`, 'skill-invocations.jsonl');
+  } catch (err) {
+    return mkProbeError(phase, err);
+  }
+}
+
+/**
+ * 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`
+ * with `dryRun: true` (SKIPs the candidate-sidecar merge — no write) and the
+ * operator confidence-floor delivery gate. 0 proposals above floor → skip.
+ * runReconcile never throws; an engine `error` is treated fail-open (run).
+ */
+async function decideReconcile({ repoRoot, cfg }) {
+  const phase = '3.6.8';
+  try {
+    if (isPersistenceOff(cfg)) return mkSkip(phase, 'persistence=false', 'config-gate');
+    if (cfg?.reconcile?.enabled !== true) {
+      return mkSkip(phase, 'disabled (reconcile.enabled=false)', 'config-gate');
+    }
+    const learningsPath = path.join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
+    if (!existsSync(learningsPath)) {
+      return mkSkip(phase, 'learnings.jsonl absent', 'learnings.jsonl');
+    }
+    const { proposals, summary, error } = await runReconcile({
+      repoRoot,
+      ruleExpiryDays: cfg?.reconcile?.['rule-expiry-days'] ?? undefined,
+      minRuleDays: cfg?.reconcile?.['min-rule-days'] ?? undefined,
+      minInsightChars: cfg?.reconcile?.['min-insight-chars'] ?? undefined,
+      now: new Date(),
+      dryRun: true, // never write the candidate sidecar from the aggregator
+    });
+    if (error) return mkProbeError(phase, new Error(error)); // fail-open on engine error
+    const floor = cfg?.reconcile?.['confidence-floor'] ?? 0.5;
+    const surfaced = (Array.isArray(proposals) ? proposals : []).filter(
+      (p) => typeof p.confidence === 'number' && p.confidence >= floor,
+    );
+    if (surfaced.length === 0) {
+      return mkSkip(
+        phase,
+        `0 proposals above confidence floor (eligible=${summary?.eligible ?? 0}, floor=${floor})`,
+        'reconcile-dry-run',
+      );
+    }
+    return mkRun(phase, `${surfaced.length} proposal(s) above confidence floor`, 'reconcile-dry-run');
+  } catch (err) {
+    return mkProbeError(phase, err);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Report builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the compact one-line skip report from a plan.
+ *
+ * @param {PhaseDecision[]} plan
+ * @returns {string}
+ */
+export function buildSkippedReport(plan) {
+  const parts = (Array.isArray(plan) ? plan : []).map((d) => {
+    const verb = d.run ? 'RUN' : 'skipped';
+    return `${d.phase} ${verb} (${d.reason})`;
+  });
+  return `Tail-Diät: ${parts.join(' · ')}`;
+}
+
+// ---------------------------------------------------------------------------
+// Main aggregator
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the run/skip plan for the six session-end Phase 3.6.x tail phases.
+ *
+ * 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.
+ *
+ * @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()).
+ * @returns {Promise<TailPlan>}
+ */
+export async function planTailPhases({ repoRoot, config, sessionId, platform, memoryDir } = {}) {
+  const cfg = config ?? {};
+  try {
+    const plan = await Promise.all([
+      decideMemoryProposals({ repoRoot, cfg }),
+      decideExpiredSweep({ repoRoot }),
+      decideAutoDream({ repoRoot, cfg, platform, memoryDir }),
+      decideSkillJudge({ repoRoot, cfg, sessionId }),
+      decideAutoDialectic({ repoRoot, cfg }),
+      decideReconcile({ repoRoot, cfg }),
+    ]);
+    return { plan, skippedReport: buildSkippedReport(plan) };
+  } catch (err) {
+    // Top-level fail-open guard: run the full tail rather than lose it silently.
+    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'),
+    );
+    return { plan, skippedReport: buildSkippedReport(plan) };
+  }
+}