session-orchestrator 3.16.0

package/scripts/lib/memory-cleanup/worktree-sweep.mjs

@@ -0,0 +1,108 @@
+/**
+ * worktree-sweep.mjs — Stale auto-promoted worktree detection helpers.
+ *
+ * Implements Phase 4.5 of skills/memory-cleanup/SKILL.md (#575 P3.2):
+ *   - listAutoPromotedWorktrees(repoRoot, mainCheckoutRoot)
+ *   - isWorktreeStale(wtPath, staleBranchDays)
+ *
+ * Public API:
+ *   - listAutoPromotedWorktrees(repoRoot, mainCheckoutRoot): Array<{wtPath, sessionId, branch}>
+ *   - isWorktreeStale(wtPath, staleBranchDays): boolean
+ *
+ * PRD: "Parallel-aware sessions" (#568; archived in the private Meta-Vault) §3 P3 Gherkin row 4 + §3.A P3
+ * Closes #575 P3.2
+ *
+ * DI seam (#580-DI-001): this module uses a SYNCHRONOUS `opts.execFileFn`
+ * (default `execFileSync`) because the memory-cleanup Phase 4.5 sweep runs in a
+ * synchronous coordinator step. Its sibling helper
+ * `scripts/lib/session-end/worktree-cleanup.mjs` shares the same sync
+ * `execFileFn` seam; the autopilot worktree driver
+ * (`scripts/lib/autopilot/worktree-pipeline.mjs`) deliberately uses an ASYNC
+ * `opts.$` (zx) seam instead because `enterWorktree()` is async. The seams are
+ * kept divergent on purpose — unifying them would break the sync/async boundary.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { parseSessionId } from '../session-id.mjs';
+
+/**
+ * List all auto-promoted sibling worktrees for a given main checkout root.
+ *
+ * Auto-promoted worktrees follow the layout `<parentDir>/<repoName>-<sessionId>/`,
+ * where `<sessionId>` is a semantic session-id (per `parseSessionId()` from
+ * `scripts/lib/session-id.mjs`). Random-suffix worktrees (UUID-format) are NOT
+ * auto-promoted and are excluded.
+ *
+ * @param {string} repoRoot - Current working directory (used as context; not directly
+ *   passed to git — mainCheckoutRoot is used for git worktree list).
+ * @param {string} mainCheckoutRoot - Absolute path to the main checkout (the primary
+ *   worktree). This is the anchor from which sibling worktrees are resolved.
+ * @param {object} [opts] - Optional dependency injection for testing.
+ * @param {Function} [opts.execFileFn] - Override for execFileSync (default: node:child_process execFileSync).
+ *   Signature: (file: string, args: string[], options) => string.
+ * @returns {Array<{wtPath: string, sessionId: string, branch: string}>}
+ *   Array of matching auto-promoted worktrees. Empty array on error or no candidates.
+ */
+export function listAutoPromotedWorktrees(repoRoot, mainCheckoutRoot, opts = {}) {
+  // #577 HARDEN-001: execFileSync + args ARRAY (no shell) — mainCheckoutRoot cannot inject.
+  const execFileFn = opts.execFileFn ?? execFileSync;
+  const repoName = path.basename(mainCheckoutRoot);
+  const candidates = [];
+
+  try {
+    const out = execFileFn('git', ['-C', mainCheckoutRoot, 'worktree', 'list', '--porcelain'], {
+      encoding: 'utf8',
+    });
+    const entries = out.split('\n\n').filter(Boolean);
+
+    for (const entry of entries) {
+      const wtMatch = entry.match(/^worktree (.+)$/m);
+      if (!wtMatch) continue;
+      const wtPath = wtMatch[1];
+
+      // Skip the main checkout itself
+      if (wtPath === mainCheckoutRoot) continue;
+
+      // Match auto-promoted layout: <parentDir>/<repoName>-<sessionId>
+      const basename = path.basename(wtPath);
+      if (!basename.startsWith(`${repoName}-`)) continue;
+      const sessionIdCandidate = basename.slice(repoName.length + 1);
+
+      // Verify it's a semantic session-id (not a random suffix or UUID)
+      const parsed = parseSessionId(sessionIdCandidate);
+      if (!parsed || parsed.format !== 'semantic') continue;
+
+      candidates.push({ wtPath, sessionId: sessionIdCandidate, branch: parsed.branch });
+    }
+  } catch {
+    // git failure or any other error → return no candidates (conservative no-op)
+    return [];
+  }
+
+  return candidates;
+}
+
+/**
+ * Determine whether a worktree directory is stale based on its mtime.
+ *
+ * A worktree is stale iff `mtime(wtPath) < now - staleBranchDays × 86400 × 1000`.
+ *
+ * @param {string} wtPath - Absolute path to the worktree directory.
+ * @param {number} staleBranchDays - Staleness threshold in days (from Session Config,
+ *   default 7). A worktree older than this many days is considered stale.
+ * @returns {boolean} `true` if the worktree exists and its mtime is older than the
+ *   threshold; `false` if the path does not exist, is unreadable, or is within the
+ *   threshold. Conservative no-op: missing paths return `false`.
+ */
+export function isWorktreeStale(wtPath, staleBranchDays) {
+  try {
+    const stat = statSync(wtPath);
+    const ageMs = Date.now() - stat.mtimeMs;
+    return ageMs > staleBranchDays * 24 * 60 * 60 * 1000;
+  } catch {
+    // Missing or unreadable → conservative no-op
+    return false;
+  }
+}

package/scripts/lib/memory-cleanup-stamp.mjs

@@ -0,0 +1,56 @@
+/**
+ * memory-cleanup-stamp.mjs — Pure helper: stamp `memory_cleanup_at` on a
+ * session record when `/memory-cleanup` ran this session.
+ *
+ * Issue #699 fix: a healthy no-op run of `/memory-cleanup` previously left
+ * `memory_cleanup_at` unstamped, so `auto-dream.mjs` `readDreamSignals`
+ * never advanced `lastCleanupAt` and `shouldDispatchAutoDream` kept firing a
+ * false nudge. This helper stamps the field unconditionally whenever the
+ * cleanup ran — including a healthy no-op where no memory files were mutated.
+ *
+ * Design constraints:
+ *   - Pure function — no I/O, no side-effects.
+ *   - No-throw — invalid inputs return the record unchanged (defensive).
+ *   - Testable seam — the Quality wave (Q2) unit-tests this function directly.
+ *   - No external deps — Node 20+ stdlib only (none needed here).
+ */
+
+/**
+ * Stamp `memory_cleanup_at` on a session record when `/memory-cleanup` ran.
+ *
+ * A cleanup run includes ALL outcomes: dry-run, apply-pending, AND healthy
+ * no-op (MEMORY.md already healthy — no files mutated). The cadence marker
+ * MUST advance even on a no-op so `shouldDispatchAutoDream` does not fire a
+ * false nudge on the next session.
+ *
+ * @param {object} record       The in-memory session record object (not mutated).
+ * @param {object} opts
+ * @param {boolean} opts.ranCleanup  True when `/memory-cleanup` ran this session
+ *   in any mode (dry-run, apply-pending, or interactive/healthy no-op).
+ *   False or absent → return record unchanged.
+ * @param {string}  opts.completedAt ISO-8601 UTC timestamp to write as
+ *   `memory_cleanup_at`. Typically the session's `completed_at` value.
+ *   Required when `ranCleanup === true`; if missing, returns record unchanged
+ *   (defensive — never throws).
+ * @returns {object} Shallow-cloned record with `memory_cleanup_at` set, OR
+ *   the original record object when no stamp is applied.
+ */
+export function stampMemoryCleanup(record, { ranCleanup, completedAt } = {}) {
+  // Guard: only stamp when the cleanup actually ran.
+  if (ranCleanup !== true) {
+    return record;
+  }
+
+  // Guard: completedAt is required to stamp; if missing, skip defensively.
+  if (typeof completedAt !== 'string' || completedAt.length === 0) {
+    return record;
+  }
+
+  // Guard: record must be a plain object; anything else is returned unchanged.
+  if (record === null || typeof record !== 'object' || Array.isArray(record)) {
+    return record;
+  }
+
+  // Return a shallow clone with the stamp applied — never mutate the input.
+  return { ...record, memory_cleanup_at: completedAt };
+}

package/scripts/lib/memory-paths.mjs

@@ -0,0 +1,31 @@
+/**
+ * memory-paths.mjs — Memory-directory path resolution (Issue #512).
+ *
+ * Single-source helper for resolving the Claude Code memory directory layout.
+ * Extracted from `scripts/lib/auto-dream.mjs` so memory-banner.mjs (and any
+ * future consumer) can import the path helper without pulling in the entire
+ * auto-dream surface (dream signals, sidecar I/O, decision logic).
+ *
+ * No external deps — Node 20+ stdlib only.
+ */
+
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * Resolve the project-specific memory directory used by the Claude Code harness.
+ *
+ * Mirrors the harness convention: `~/.claude/projects/<encoded-cwd>/memory/`
+ * where `<encoded-cwd>` is the cwd with BOTH `/` AND `.` replaced by `-`. The
+ * dot replacement matters for users with a trailing-`.` in their home dir
+ * (e.g. `/Users/<owner>.`) — without it the resolved path diverges from
+ * what the harness actually wrote.
+ *
+ * Verified empirically against `~/.claude/projects/` directory naming.
+ *
+ * @returns {string} Absolute path to the memory directory (not guaranteed to exist).
+ */
+export function resolveMemoryDir() {
+  const encoded = process.cwd().replaceAll('/', '-').replaceAll('.', '-');
+  return path.join(os.homedir(), '.claude', 'projects', encoded, 'memory');
+}

package/scripts/lib/memory-proposals/collector.mjs

@@ -0,0 +1,334 @@
+/**
+ * memory-proposals/collector.mjs — Read-only aggregator for the memory-proposal queue.
+ *
+ * Reads proposals.jsonl + all per-wave summary JSONs at session-end and
+ * aggregates them into a structured payload the coordinator uses to drive
+ * AUQ rendering (Phase 3.6.3).
+ *
+ * Design principles (issue #501, PRD F2.1):
+ *   - Read-only — never writes any file.
+ *   - Never throws — fs/parse errors are translated to empty/zero results.
+ *   - FIFO ordering — proposals are sorted by created_at ASC (no confidence re-sort).
+ *   - Malformed JSONL lines are silently skipped (counted in stats.parse_errors).
+ *   - Missing files → empty queue + all-zero stats (graceful degradation).
+ *
+ * No external deps — Node 20+ stdlib only.
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the path to proposals.jsonl within the repo's metrics directory.
+ *
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function proposalsJsonlPath(repoRoot) {
+  return path.join(repoRoot, '.orchestrator', 'metrics', 'proposals.jsonl');
+}
+
+/**
+ * Resolve the metrics directory where per-wave summary JSONs are stored.
+ *
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function metricsDir(repoRoot) {
+  return path.join(repoRoot, '.orchestrator', 'metrics');
+}
+
+// ---------------------------------------------------------------------------
+// Zero-value helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return a stats object with all counters set to zero.
+ *
+ * @returns {object}
+ */
+function zeroStats() {
+  return {
+    queued: 0,
+    dropped: 0,
+    below_floor: 0,
+    fs_error: 0,
+    parse_errors: 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// JSONL reader (exported for unit testing / direct use)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read proposals.jsonl and return records sorted FIFO by created_at.
+ *
+ * Malformed lines are skipped silently (a debug-level log is emitted so
+ * callers can observe them without failing). The caller receives an array
+ * of plain parsed objects — no schema validation is applied here; that is
+ * the store layer's responsibility.
+ *
+ * Uses `deserializeProposal` from schema.mjs when available; falls back to
+ * raw `JSON.parse` so the module can operate independently during testing or
+ * when I1 (schema.mjs) ships in the same wave.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot  Absolute path to the repo root.
+ * @returns {Promise<import('./schema.mjs').ProposalRecord[]>}
+ */
+export async function readProposalsJsonl({ repoRoot }) {
+  const filePath = proposalsJsonlPath(repoRoot);
+  if (!existsSync(filePath)) {
+    return [];
+  }
+
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch (err) {
+    console.error(`[memory-proposals/collector] WARN: could not read proposals.jsonl: ${err.message}`);
+    return [];
+  }
+
+  // Attempt to load deserializeProposal from schema.mjs (may not exist yet).
+  let deserialize = null;
+  try {
+    const schema = await import('./schema.mjs');
+    if (typeof schema.deserializeProposal === 'function') {
+      deserialize = schema.deserializeProposal;
+    }
+  } catch {
+    // schema.mjs not yet available — fall back to raw JSON.parse.
+  }
+
+  const lines = raw.split('\n').filter((l) => l.length > 0);
+  const records = [];
+
+  for (const line of lines) {
+    try {
+      // deserializeProposal from schema.mjs expects the raw JSONL line (it
+      // does JSON.parse internally). Passing a pre-parsed object trips its
+      // `typeof line !== 'string'` guard and returns null for every record.
+      // Fall back to raw JSON.parse only when schema.mjs is unavailable.
+      const record = deserialize ? deserialize(line) : JSON.parse(line);
+      if (record !== null && record !== undefined) {
+        records.push(record);
+      }
+    } catch {
+      // Malformed line — skip silently per spec.
+      console.debug(`[memory-proposals/collector] DEBUG: skipped malformed JSONL line`);
+    }
+  }
+
+  // FIFO: sort by created_at ascending (lexicographic ISO 8601 is safe for this).
+  records.sort((a, b) => {
+    const aTs = typeof a.created_at === 'string' ? a.created_at : '';
+    const bTs = typeof b.created_at === 'string' ? b.created_at : '';
+    if (aTs < bTs) return -1;
+    if (aTs > bTs) return 1;
+    return 0;
+  });
+
+  return records;
+}
+
+// ---------------------------------------------------------------------------
+// Per-wave summary reader
+// ---------------------------------------------------------------------------
+
+/**
+ * Read all `proposals-summary-*.json` files from the metrics directory.
+ *
+ * Returns a map of wave_id → parsed summary object. Files that cannot be
+ * parsed are skipped (fs_error is counted separately in collectProposals).
+ *
+ * @param {string} repoRoot
+ * @returns {Promise<Record<string, object>>}
+ */
+async function readPerWaveSummaries(repoRoot) {
+  const dir = metricsDir(repoRoot);
+  const summaries = {};
+
+  if (!existsSync(dir)) {
+    return summaries;
+  }
+
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch (err) {
+    console.error(`[memory-proposals/collector] WARN: could not read metrics dir: ${err.message}`);
+    return summaries;
+  }
+
+  const summaryFiles = names.filter(
+    (n) => n.startsWith('proposals-summary-') && n.endsWith('.json')
+  );
+
+  for (const filename of summaryFiles) {
+    const filePath = path.join(dir, filename);
+    try {
+      const raw = await readFile(filePath, 'utf8');
+      const parsed = JSON.parse(raw);
+      // Derive the wave_id from the filename: proposals-summary-W1.json → W1
+      const waveId = filename
+        .replace(/^proposals-summary-/, '')
+        .replace(/\.json$/, '');
+      summaries[waveId] = parsed;
+    } catch (err) {
+      console.error(
+        `[memory-proposals/collector] WARN: could not parse ${filename}: ${err.message}`
+      );
+      // Silently skip — the caller gets the fs_error count from collectProposals.
+    }
+  }
+
+  return summaries;
+}
+
+// ---------------------------------------------------------------------------
+// Stats accumulator
+// ---------------------------------------------------------------------------
+
+/**
+ * Accumulate stats from all per-wave summary objects into a single stats record.
+ *
+ * Recognised summary fields (store.mjs convention):
+ *   queued, dropped, below_floor, fs_error
+ * (wrong-context rejections exit at CLI before reaching store; not tracked here per Q1 W4 finding.)
+ *
+ * Unknown fields in summaries are ignored.
+ *
+ * @param {Record<string, object>} summaries
+ * @returns {object} accumulated stats (without parse_errors — caller fills that)
+ */
+function accumulateSummaryStats(summaries) {
+  const stats = zeroStats();
+  const KNOWN_FIELDS = ['queued', 'dropped', 'below_floor', 'fs_error'];
+
+  for (const summary of Object.values(summaries)) {
+    if (!summary || typeof summary !== 'object') continue;
+    for (const field of KNOWN_FIELDS) {
+      if (typeof summary[field] === 'number' && Number.isFinite(summary[field])) {
+        stats[field] += summary[field];
+      }
+    }
+  }
+
+  return stats;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect all memory proposals at session-end: read proposals.jsonl + all
+ * per-wave summary JSONs, aggregate into a structured payload.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot      Absolute path to the repo root.
+ * @param {number|null} [args.minConfidence=null]
+ *   Optional collect-emit confidence floor (issue #566). When a finite number
+ *   is supplied, records with `record.confidence < minConfidence` are dropped
+ *   from the returned `queue` BEFORE the function returns. When `null`,
+ *   `undefined`, or non-numeric, no filtering is applied (back-compat).
+ *
+ *   This is a SECOND gate above the write-time
+ *   `memory.proposals.confidence-floor` enforced by
+ *   `scripts/memory-propose.mjs` — the per-record write-floor runs first,
+ *   then the collect-emit floor here filters what surfaces to the operator's
+ *   AUQ at session-end Phase 3.6.3. `stats` reflect the full intake (not
+ *   post-filter) because they are accumulated from the per-wave summaries,
+ *   not from the returned queue.
+ * @returns {Promise<{
+ *   queue: object[],
+ *   stats: {
+ *     queued: number,
+ *     dropped: number,
+ *     below_floor: number,
+ *     fs_error: number,
+ *     parse_errors: number,
+ *   },
+ *   perWaveSummaries: Record<string, object>,
+ * }>}
+ */
+export async function collectProposals({ repoRoot, minConfidence = null }) {
+  // Short-circuit: if proposals.jsonl doesn't exist, nothing was ever queued.
+  const jsonlPath = proposalsJsonlPath(repoRoot);
+  if (!existsSync(jsonlPath)) {
+    return {
+      queue: [],
+      stats: zeroStats(),
+      perWaveSummaries: {},
+    };
+  }
+
+  // Run JSONL read and per-wave summary read concurrently.
+  const [queueResult, perWaveSummaries] = await Promise.allSettled([
+    readProposalsJsonl({ repoRoot }),
+    readPerWaveSummaries(repoRoot),
+  ]);
+
+  // Extract results, treating rejections as empty/no-op (should not happen
+  // since both functions catch internally, but guard defensively).
+  let queue = queueResult.status === 'fulfilled' ? queueResult.value : [];
+  const summaries =
+    perWaveSummaries.status === 'fulfilled' ? perWaveSummaries.value : {};
+
+  if (queueResult.status === 'rejected') {
+    console.error(
+      `[memory-proposals/collector] WARN: readProposalsJsonl rejected unexpectedly: ${queueResult.reason}`
+    );
+  }
+  if (perWaveSummaries.status === 'rejected') {
+    console.error(
+      `[memory-proposals/collector] WARN: readPerWaveSummaries rejected unexpectedly: ${perWaveSummaries.reason}`
+    );
+  }
+
+  // Accumulate stats from per-wave summaries.
+  const stats = accumulateSummaryStats(summaries);
+
+  // Count parse_errors: lines in the JSONL that were NOT successfully parsed.
+  // We approximate this by reading the raw line count vs the queue length.
+  // This requires a second read-pass on the raw file — use the already-read
+  // content by re-counting; since readProposalsJsonl does the heavy lifting,
+  // we derive parse_errors from the difference between raw non-empty lines
+  // and successfully parsed records.
+  let parseErrors = 0;
+  try {
+    const raw = await readFile(jsonlPath, 'utf8');
+    const rawLineCount = raw.split('\n').filter((l) => l.length > 0).length;
+    parseErrors = Math.max(0, rawLineCount - queue.length);
+  } catch {
+    // File became unreadable between the two reads — treat as 0 parse errors.
+  }
+  stats.parse_errors = parseErrors;
+
+  // Collect-emit confidence filter (issue #566). Applies AFTER parse_errors
+  // is computed against the raw-line count, so parse_errors stays anchored to
+  // what the file actually contains. The filter only affects what the
+  // coordinator surfaces to the operator AUQ; stats reflect the full intake.
+  if (typeof minConfidence === 'number' && Number.isFinite(minConfidence)) {
+    queue = queue.filter((record) => {
+      const c = record && typeof record.confidence === 'number' ? record.confidence : null;
+      // Records with no confidence field (or NaN) are kept — the gate only
+      // drops records that actively report a confidence below the floor.
+      if (c === null || !Number.isFinite(c)) return true;
+      return c >= minConfidence;
+    });
+  }
+
+  return {
+    queue,
+    stats,
+    perWaveSummaries: summaries,
+  };
+}