abmind 0.2.5 → 0.2.6

package/dist/src/sleep/orchestrator.js

@@ -16,10 +16,9 @@
  */
 import { localISO } from "../local-time.js";
 import { getAbmindEnv } from "../env-schema.js";
-import { join, basename, dirname } from "node:path";
+import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { appendFileSync, mkdirSync, existsSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
-import { atomicWriteSync } from "../atomic-write.js";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { MemoryManager } from "../memory-manager.js";
 import { loadMemoryConfig } from "../memory-config.js";
 import { SleepStateGatherer } from "../sleep-state-gatherer.js";
@@ -27,23 +26,18 @@ import { loadSleepSteps, buildSleepVars, substituteVars } from "../sleep-pipelin
 import { buildDailySummary, writeDailyFile, LLMUnavailableError } from "../sleep-pipeline.js";
 import { extractFromDaily } from "../sleep-pipeline.js";
 import { logInfo, logWarn, logError } from "../mem-logger.js";
-import { redactSecrets } from "../redact-secrets.js";
 import { localDate } from "../local-time.js";
 import { parseLevel, DEFAULT_LEVEL } from "./levels.js";
+import { readStateFile, writeStateFile, runWiredPreTasks, formatWiredResults, fireOnStep } from "./state.js";
+import { buildSnapshotSummary, writeAuditLog } from "./audit.js";
+import { toDateStr, toIsoDate, scanPreviousLocks } from "./locks.js";
+import { redactSecrets } from "../redact-secrets.js";
+import { ModelUnavailableError, LlmBudget, sendWithRetry, DEFAULT_TRANSPORT_RETRY_WINDOW_MS, MAX_RETRIES } from "./llm-budget.js";
+import { runCatchUp } from "./catchup.js";
 const TAG = "abmind-sleep";
-/** Format a timestamp as YYYYMMDD (for lock file names). */
-function toDateStr(ts) {
-    const d = new Date(ts);
-    return `${d.getFullYear()}${String(d.getMonth() + 1).padStart(2, "0")}${String(d.getDate()).padStart(2, "0")}`;
-}
-/** Format a timestamp as YYYY-MM-DD (for daily file paths). */
-function toIsoDate(ts) {
-    const d = new Date(ts);
-    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
-}
 /** Steps whose failure blocks watermark advance. Public so tests can derive reject targets. */
-export const ESSENTIAL_STEPS = new Set(["daily-summary", "extract-memories", "retrospective"]);
-const CATCHUP_MAX_AGE_DAYS = 3;
+// Re-exported from catchup.ts — kept here for backward compat of any direct orchestrator imports.
+export { ESSENTIAL_STEPS } from "./catchup.js";
 /** Thrown by runSleepCycle when memory layer fails to initialize. */
 export class SleepInitError extends Error {
     constructor(message) { super(message); this.name = "SleepInitError"; }
@@ -52,16 +46,6 @@ export class SleepInitError extends Error {
 export class SleepTimeoutError extends Error {
     constructor(message) { super(message); this.name = "SleepTimeoutError"; }
 }
-/** Best-effort onStep invoker — swallow handler errors so a display callback
- *  can never break the pipeline. */
-function fireOnStep(handler, e) {
-    if (!handler)
-        return;
-    try {
-        handler(e);
-    }
-    catch { /* host display only — never fail the cycle */ }
-}
 export function parseArgs(argv) {
     const args = argv.slice(2);
     const parsed = { dryRun: false, verbose: false, force: false };
@@ -80,473 +64,9 @@ export function parseArgs(argv) {
     }
     return parsed;
 }
-// getPrimaryUserId moved to SleepDataAccess in memory package
-function readStateFile(path) {
-    try {
-        if (!existsSync(path))
-            return null;
-        const raw = JSON.parse(readFileSync(path, "utf-8"));
-        if (typeof raw !== "object" || raw === null || !raw.steps)
-            return null;
-        // Backfill defaults for legacy lock files
-        if (!raw.status)
-            raw.status = "ongoing";
-        if (raw.llmCalls == null)
-            raw.llmCalls = 0;
-        return raw;
-    }
-    catch {
-        return null;
-    }
-}
-function writeStateFile(path, state) {
-    atomicWriteSync(path, JSON.stringify(state, null, 2));
-}
-// ── Wired pre-tasks (delegated to abmind MaintenanceService) ────────────────
-async function runWiredPreTasks(sleepData, memoryDir, memory) {
-    const r = await memory.maintenance.runPreSleepTasks(memory, sleepData);
-    // Bridge-side: log rotation (not memory's concern)
-    let logsDeleted = 0;
-    try {
-        const logsDir = join(memoryDir, "..", "logs");
-        if (existsSync(logsDir)) {
-            const cutoff = Date.now() - 7 * 86400000;
-            for (const f of readdirSync(logsDir)) {
-                if (!f.startsWith("bridge-") || !f.endsWith(".log"))
-                    continue;
-                const match = f.match(/bridge-(\d{4}-\d{2}-\d{2})\.log/);
-                if (match && new Date(match[1]).getTime() < cutoff) {
-                    unlinkSync(join(logsDir, f));
-                    logsDeleted++;
-                }
-            }
-        }
-    }
-    catch (err) {
-        logWarn(TAG, `[WIRED] log rotation: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    return { purged: r.purged, deduped: r.deduped, embedded: r.embedded, anomaliesFixed: r.anomaliesFixed, walOk: r.walOk, ftsOk: r.ftsOk, logsDeleted };
-}
-function formatWiredResults(r) {
-    const parts = [];
-    if (r.purged > 0)
-        parts.push(`${r.purged} garbage purged`);
-    if (r.deduped > 0)
-        parts.push(`${r.deduped} dupes deleted`);
-    parts.push(`WAL ${r.walOk ? "ok" : "FAILED"}`);
-    parts.push(`FTS ${r.ftsOk ? "ok" : "FAILED"}`);
-    if (r.embedded > 0)
-        parts.push(`${r.embedded} embedded`);
-    if (r.anomaliesFixed > 0)
-        parts.push(`${r.anomaliesFixed} anomalies fixed`);
-    if (r.logsDeleted > 0)
-        parts.push(`${r.logsDeleted} old logs deleted`);
-    return parts.length > 0 ? parts.join(", ") : "nothing to do";
-}
+// ── Subagent invocation ─────────────────────────────────────────────────────
+/** LLM call entry for sleep steps — caller provides the runtime via RunOpts. */
 // ── Transport ───────────────────────────────────────────────────────────────
-// (SleepRuntime is imported at the top of the file.)
-const MAX_RETRIES = 3;
-const TRANSPORT_MAX_RETRIES = 6;
-const DEFAULT_TRANSPORT_RETRY_WINDOW_MS = 8 * 60_000; // 8 minutes
-/** Thrown by sendWithRetry when runtime.complete() throws on every attempt within the retry window.
- *  Extends LLMUnavailableError so buildDailySummary and extractFromDaily rethrow it naturally
- *  (those functions check instanceof LLMUnavailableError to propagate errors up). */
-export class ModelUnavailableError extends LLMUnavailableError {
-    constructor(stepName) {
-        super(`Model unavailable for step "${stepName}" after retry window`);
-        this.name = "ModelUnavailableError";
-    }
-}
-/** Budget tracker — shared across all sendWithRetry calls in a sleep cycle. */
-class LlmBudget {
-    state;
-    statePath;
-    exhausted = false;
-    constructor(state, statePath) {
-        this.state = state;
-        this.statePath = statePath;
-    }
-    /** Increment counter, return false if budget exhausted. */
-    consume() {
-        this.state.llmCalls = (this.state.llmCalls ?? 0) + 1;
-        writeStateFile(this.statePath, this.state);
-        if (this.state.llmCalls > getAbmindEnv().sleepMaxLlmCalls) {
-            this.exhausted = true;
-            return false;
-        }
-        return true;
-    }
-    get calls() { return this.state.llmCalls ?? 0; }
-}
-async function sendWithRetry(runtime, prompt, stepName, _verbose, budget, delayMs = 6000, transportBackoffMs = (n) => Math.min(30_000 * Math.pow(2, n - 1), 120_000), transportRetryWindowMs = DEFAULT_TRANSPORT_RETRY_WINDOW_MS, nowFn = Date.now) {
-    const deadline = nowFn() + transportRetryWindowMs;
-    let emptyAttempts = 0;
-    let transportAttempts = 0;
-    // Budget-exhaustion pre-check: if we are already over the cap, bail immediately.
-    // This mirrors the old pre-loop consume() guard without burning a call.
-    if (budget?.exhausted) {
-        logWarn(TAG, `[BUDGET] LLM call limit (${getAbmindEnv().sleepMaxLlmCalls}) reached at step ${stepName} — suspending`);
-        return null;
-    }
-    while (true) {
-        try {
-            const result = await runtime.complete(prompt);
-            // Real call reached the model — count it now (success OR empty, never a throw).
-            if (budget && !budget.consume()) {
-                logWarn(TAG, `[BUDGET] LLM call limit (${getAbmindEnv().sleepMaxLlmCalls}) reached at step ${stepName} — suspending`);
-                return null;
-            }
-            if (!result || !result.trim()) {
-                emptyAttempts++;
-                logWarn(TAG, `Step ${stepName} attempt ${emptyAttempts}/${MAX_RETRIES} returned empty response`);
-                if (emptyAttempts >= MAX_RETRIES) {
-                    logError(TAG, `Step ${stepName} failed after ${MAX_RETRIES} attempts (empty), skipping`);
-                    return null;
-                }
-                if (delayMs > 0)
-                    await new Promise(r => setTimeout(r, delayMs));
-                continue;
-            }
-            return result;
-        }
-        catch (err) {
-            // Transport failure — model unreachable. Do NOT consume budget (no tokens used).
-            transportAttempts++;
-            const msg = err instanceof Error ? err.message : String(err);
-            const backoff = transportBackoffMs(transportAttempts);
-            const timeRemaining = deadline - nowFn();
-            logWarn(TAG, `Step ${stepName} transport fail (${transportAttempts}/${TRANSPORT_MAX_RETRIES}): ${msg}`);
-            if (transportAttempts >= TRANSPORT_MAX_RETRIES || timeRemaining <= backoff) {
-                logError(TAG, `Step ${stepName} — model unavailable after ${transportAttempts} attempt(s), ${Math.round(transportRetryWindowMs / 60_000)}min window exhausted`);
-                throw new ModelUnavailableError(stepName);
-            }
-            logInfo(TAG, `[SLEEP] Model unreachable — waiting ${Math.round(backoff / 1000)}s before retry (step ${stepName})`);
-            if (backoff > 0)
-                await new Promise(r => setTimeout(r, backoff));
-        }
-    }
-}
-// ── Audit trail helpers ─────────────────────────────────────────────────────
-function buildSnapshotSummary(snapshot) {
-    return [
-        `Working dirs: ${snapshot.workingDirs.length}`,
-        `Messages: ${snapshot.dbStats.messageCount}`,
-        `Embeddings: ${snapshot.dbStats.embeddingCount}`,
-        `Extracted memories: ${snapshot.dbStats.extractedMemoryCount}`,
-        `Disk: ${(snapshot.diskUsageBytes / 1024 / 1024).toFixed(1)} MB / ${(snapshot.diskBudgetBytes / 1024 / 1024).toFixed(0)} MB`,
-        `Topics: ${snapshot.topicFiles.length}`,
-        `FTS5: messages=${snapshot.fts5Health.messages_fts}, extracted=${snapshot.fts5Health.extracted_memories_fts}, original=${snapshot.fts5Health.extracted_memories_original_fts}`,
-    ].join(", ");
-}
-/**
- * Parse outcome counts from the subagent's free-form text response.
- *
- * The subagent response is unstructured text, so we use best-effort regex
- * matching for common patterns like "consolidated 3 files", "pruned 42
- * messages", etc. Returns 0 for any count that can't be parsed.
- */
-function parseOutcomesFromResponse(response) {
-    const defaults = {
-        filesConsolidated: 0,
-        messagesPruned: 0,
-        embeddingsRemoved: 0,
-        sessionsCleaned: 0,
-        topicsMerged: 0,
-        topicsDeleted: 0,
-    };
-    if (!response)
-        return defaults;
-    const text = response.toLowerCase();
-    // Each pattern array contains regexes to try in order for a given outcome.
-    // We take the first match found. Patterns cover both "verb N noun" and
-    // "N noun verb" orderings that an LLM might produce.
-    const patterns = [
-        {
-            key: "filesConsolidated",
-            regexes: [
-                /consolidat\w*\s+(\d+)\s+(?:file|dir|working)/i,
-                /(\d+)\s+(?:file|dir|working\s*dir)\w*\s+consolidat/i,
-                /files?\s+consolidated\s*:\s*(\d+)/i,
-            ],
-        },
-        {
-            key: "messagesPruned",
-            regexes: [
-                /prun\w*\s+(\d+)\s+message/i,
-                /(\d+)\s+message\w*\s+prun/i,
-                /(?:delet|remov)\w*\s+(\d+)\s+message/i,
-                /(\d+)\s+message\w*\s+(?:delet|remov)/i,
-                /messages?\s+pruned\s*:\s*(\d+)/i,
-            ],
-        },
-        {
-            key: "embeddingsRemoved",
-            regexes: [
-                /(?:remov|delet|clean)\w*\s+(\d+)\s+embedding/i,
-                /(\d+)\s+embedding\w*\s+(?:remov|delet|clean)/i,
-                /embeddings?\s+removed\s*:\s*(\d+)/i,
-            ],
-        },
-        {
-            key: "sessionsCleaned",
-            regexes: [
-                /(?:clean|delet|remov)\w*\s+(\d+)\s+session/i,
-                /(\d+)\s+session\w*\s+(?:clean|delet|remov)/i,
-                /sessions?\s+cleaned\s*:\s*(\d+)/i,
-            ],
-        },
-        {
-            key: "topicsMerged",
-            regexes: [
-                /merg\w*\s+(\d+)\s+topic/i,
-                /(\d+)\s+topic\w*\s+merg/i,
-                /topics?\s+merged\s*:\s*(\d+)/i,
-            ],
-        },
-        {
-            key: "topicsDeleted",
-            regexes: [
-                /delet\w*\s+(\d+)\s+topic/i,
-                /(\d+)\s+topic\w*\s+delet/i,
-                /topics?\s+deleted\s*:\s*(\d+)/i,
-            ],
-        },
-    ];
-    for (const { key, regexes } of patterns) {
-        for (const regex of regexes) {
-            const match = text.match(regex);
-            if (match?.[1]) {
-                const parsed = parseInt(match[1], 10);
-                if (!isNaN(parsed) && parsed >= 0) {
-                    defaults[key] = parsed;
-                    break;
-                }
-            }
-        }
-    }
-    return defaults;
-}
-function writeAuditLog(memoryDir, entry) {
-    const sleepDir = join(memoryDir, "sleep");
-    mkdirSync(sleepDir, { recursive: true });
-    const suffix = [
-        ``,
-        `---`,
-        ``,
-        `## CLI Wrapper`,
-        ``,
-        `**Timestamp:** ${entry.timestamp}`,
-        `**Model:** ${entry.model}`,
-        ``,
-        `### State Snapshot`,
-        `${entry.stateSnapshotSummary}`,
-        ``,
-        `### Outcomes`,
-        `- Files consolidated: ${entry.outcomes.filesConsolidated}`,
-        `- Messages pruned: ${entry.outcomes.messagesPruned}`,
-        `- Embeddings removed: ${entry.outcomes.embeddingsRemoved}`,
-        `- Sessions cleaned: ${entry.outcomes.sessionsCleaned}`,
-        `- Topics merged: ${entry.outcomes.topicsMerged}`,
-        `- Topics deleted: ${entry.outcomes.topicsDeleted}`,
-        entry.error ? `\n### Error\n${entry.error}` : "",
-    ].join("\n");
-    // Find the subagent's audit file and append to it
-    const today = localDate().replace(/-/g, "");
-    try {
-        const files = readdirSync(sleepDir)
-            .filter(f => f.startsWith(`sleep_${today}`) && f.endsWith(".md"))
-            .sort();
-        if (files.length > 0) {
-            const target = join(sleepDir, files[files.length - 1]);
-            const existingLines = readFileSync(target, "utf-8").split("\n").length;
-            if (existingLines < 50) {
-                logWarn(TAG, `Sleep audit suspiciously short (${existingLines} lines) — subagent may have truncated`);
-            }
-            appendFileSync(target, redactSecrets(suffix), "utf-8");
-            return;
-        }
-    }
-    catch { /* fall through to standalone */ }
-    // Fallback: no subagent file found — write standalone
-    const now = new Date();
-    const dateStr = localDate().replace(/-/g, "");
-    const timeStr = now.toTimeString().slice(0, 5).replace(/:/g, "");
-    const filename = `sleep_${dateStr}_${timeStr}.md`;
-    writeFileSync(join(sleepDir, filename), redactSecrets(`# Sleep Audit Log${suffix}`), "utf-8");
-}
-function scanPreviousLocks(sleepDir, todayStr) {
-    if (!existsSync(sleepDir))
-        return [];
-    const locks = [];
-    const todayMs = dateStrToMs(todayStr);
-    for (const f of readdirSync(sleepDir)) {
-        const m = f.match(/^sleep_(\d{8})\.lock$/);
-        if (!m || m[1] === todayStr)
-            continue;
-        const state = readStateFile(join(sleepDir, f));
-        if (!state)
-            continue;
-        const ageDays = Math.round((todayMs - dateStrToMs(m[1])) / 86400000);
-        if (ageDays > 0)
-            locks.push({ path: join(sleepDir, f), dateStr: m[1], state, ageDays });
-    }
-    return locks.sort((a, b) => b.dateStr.localeCompare(a.dateStr)); // newest first
-}
-function dateStrToMs(ds) {
-    return new Date(`${ds.slice(0, 4)}-${ds.slice(4, 6)}-${ds.slice(6, 8)}T00:00:00`).getTime();
-}
-function dateStrToFormatted(ds) {
-    return `${ds.slice(0, 4)}-${ds.slice(4, 6)}-${ds.slice(6, 8)}`;
-}
-function failedEssentials(state) {
-    const failed = [];
-    for (const name of ESSENTIAL_STEPS) {
-        const s = state.steps[name];
-        if (!s || s.status === "failed" || s.status === "timeout" || s.status === "pending") {
-            failed.push(name);
-        }
-    }
-    return failed;
-}
-async function runCatchUp(locks, sleepData, memoryConfig, steps, flags, runtime, budget, retryDelayMs = 6000, onStep) {
-    for (const lock of locks) {
-        if (lock.ageDays > CATCHUP_MAX_AGE_DAYS) {
-            logError(TAG, `[CATCH-UP] Abandoning stale lock ${basename(lock.path)} — ${lock.ageDays} days old, data unrecoverable`);
-            unlinkSync(lock.path);
-            continue;
-        }
-        const needed = failedEssentials(lock.state);
-        if (needed.length === 0) {
-            logInfo(TAG, `[CATCH-UP] Cleaning up completed lock ${basename(lock.path)}`);
-            unlinkSync(lock.path);
-            continue;
-        }
-        logInfo(TAG, `[CATCH-UP] ${basename(lock.path)} — recovering: ${needed.join(", ")}`);
-        // 04a — daily summary with date-range
-        if (needed.includes("daily-summary")) {
-            const start = Date.now();
-            try {
-                const ctxWindow = getAbmindEnv().sleepCtxWindow;
-                const userId = sleepData.getPrimaryUserId();
-                const dayStart = dateStrToMs(lock.dateStr);
-                const dayEnd = dayStart + 86400000;
-                const summary = await buildDailySummary(sleepData.getDb(), (p) => sendWithRetry(runtime, p, "catch-up-04a", flags.verbose, budget, retryDelayMs).then(r => { if (r === null)
-                    throw new LLMUnavailableError(); return r; }), {
-                    ctxWindow, memoryDir: memoryConfig.memoryDir, userId, watermarkTs: 0,
-                    dateRange: { startTs: dayStart, endTs: dayEnd },
-                });
-                if (summary) {
-                    writeDailyFile(memoryConfig.memoryDir, dateStrToFormatted(lock.dateStr), summary);
-                    lock.state.steps["daily-summary"] = { status: "ok", duration: Math.round((Date.now() - start) / 100) / 10 };
-                }
-                else {
-                    lock.state.steps["daily-summary"] = { status: "skipped" };
-                }
-                logInfo(TAG, `[CATCH-UP] ✓ 04a-daily-summary for ${lock.dateStr} (${((Date.now() - start) / 1000).toFixed(1)}s)`);
-                // #895: emit terminal event for catch-up daily-summary
-                fireOnStep(onStep, {
-                    name: "daily-summary", filename: "catch-up",
-                    index: 0, total: 0,
-                    phase: summary ? "done" : "skipped",
-                });
-            }
-            catch (err) {
-                logWarn(TAG, `[CATCH-UP] ✗ 04a-daily-summary for ${lock.dateStr}: ${err instanceof Error ? err.message : String(err)}`);
-                lock.state.steps["daily-summary"] = { status: "failed", duration: Math.round((Date.now() - start) / 100) / 10 };
-                // #895: emit failed for catch-up daily-summary
-                fireOnStep(onStep, {
-                    name: "daily-summary", filename: "catch-up",
-                    index: 0, total: 0,
-                    phase: "failed",
-                });
-            }
-            writeStateFile(lock.path, lock.state);
-        }
-        // 04b — extract memories from daily (needs daily file to exist)
-        if (needed.includes("extract-memories")) {
-            const dailyPath = join(memoryConfig.memoryDir, "daily", `daily_${dateStrToFormatted(lock.dateStr)}.md`);
-            if (!existsSync(dailyPath)) {
-                logInfo(TAG, `[CATCH-UP] ⏭ 04b — no daily file for ${lock.dateStr}`);
-                lock.state.steps["extract-memories"] = { status: "skipped" };
-                // #895: emit skip when no daily file for catch-up
-                fireOnStep(onStep, {
-                    name: "extract-memories", filename: "catch-up",
-                    index: 0, total: 0,
-                    phase: "skipped",
-                });
-            }
-            else {
-                const start = Date.now();
-                try {
-                    const userId = sleepData.getPrimaryUserId();
-                    const result = await extractFromDaily(dailyPath, userId, (p) => sendWithRetry(runtime, p, "catch-up-04b", flags.verbose, budget, retryDelayMs).then(r => { if (r === null)
-                        throw new LLMUnavailableError(); return r; }));
-                    lock.state.steps["extract-memories"] = { status: "ok", duration: Math.round((Date.now() - start) / 100) / 10 };
-                    logInfo(TAG, `[CATCH-UP] ✓ 04b-extract-memories for ${lock.dateStr} (${((Date.now() - start) / 1000).toFixed(1)}s) — ${result.slice(0, 80)}`);
-                    // #895: emit done for catch-up extract-memories
-                    fireOnStep(onStep, {
-                        name: "extract-memories", filename: "catch-up",
-                        index: 0, total: 0,
-                        phase: "done",
-                    });
-                }
-                catch (err) {
-                    logWarn(TAG, `[CATCH-UP] ✗ 04b for ${lock.dateStr}: ${err instanceof Error ? err.message : String(err)}`);
-                    lock.state.steps["extract-memories"] = { status: "failed", duration: Math.round((Date.now() - start) / 100) / 10 };
-                    // #895: emit failed for catch-up extract-memories
-                    fireOnStep(onStep, {
-                        name: "extract-memories", filename: "catch-up",
-                        index: 0, total: 0,
-                        phase: "failed",
-                    });
-                }
-            }
-            writeStateFile(lock.path, lock.state);
-        }
-        // Prompt-driven essentials (retrospective — now includes extraction)
-        for (const stepName of ["retrospective"]) {
-            if (!needed.includes(stepName))
-                continue;
-            const step = steps.find(s => s.name === stepName);
-            if (!step) {
-                logWarn(TAG, `[CATCH-UP] Step file not found: ${stepName}`);
-                continue;
-            }
-            const start = Date.now();
-            const response = await sendWithRetry(runtime, step.rawPrompt, `catch-up-${stepName}`, flags.verbose, budget, retryDelayMs);
-            if (response) {
-                lock.state.steps[stepName] = { status: "ok", duration: Math.round((Date.now() - start) / 100) / 10 };
-                logInfo(TAG, `[CATCH-UP] ✓ ${stepName} (${((Date.now() - start) / 1000).toFixed(1)}s)`);
-                // #895: emit done for catch-up retrospective
-                fireOnStep(onStep, {
-                    name: stepName, filename: "catch-up",
-                    index: 0, total: 0,
-                    phase: "done",
-                });
-            }
-            else {
-                lock.state.steps[stepName] = { status: "failed", duration: Math.round((Date.now() - start) / 100) / 10 };
-                logWarn(TAG, `[CATCH-UP] ✗ ${stepName}`);
-                // #895: emit failed for catch-up retrospective
-                fireOnStep(onStep, {
-                    name: stepName, filename: "catch-up",
-                    index: 0, total: 0,
-                    phase: "failed",
-                });
-            }
-            writeStateFile(lock.path, lock.state);
-        }
-        // Final check: all essentials recovered?
-        const stillFailing = failedEssentials(lock.state);
-        if (stillFailing.length === 0) {
-            logInfo(TAG, `[CATCH-UP] ✅ ${basename(lock.path)} — all essentials recovered, lock deleted`);
-            unlinkSync(lock.path);
-        }
-        else {
-            logWarn(TAG, `[CATCH-UP] ${basename(lock.path)} — still failing: ${stillFailing.join(", ")} (failing ${lock.ageDays} day(s))`);
-        }
-    }
-}
 // ── Main orchestration ──────────────────────────────────────────────────────
 /**
  * Run the full sleep cycle. Extracted from main() for testability (#175).