@lh8ppl/claude-memory-kit 0.4.0 → 0.4.2

package/src/compaction-state.mjs

@@ -0,0 +1,204 @@
+// Compaction-state deep module (Task 167, D-206/D-207).
+//
+// Owns the single question "does memory need compacting right now, and is the
+// scheduled cron alive?" — replacing the old detectStaleness gating that
+// short-circuited to 'cron-active' on the mere EXISTENCE of a cron-registered
+// sentinel (so a registered-but-dead cron disabled the lazy roll and now.md grew
+// unbounded — the v0.4.0 dogfood's 410 KB freeze).
+//
+// Two public methods (the deep interface — Q3):
+//
+//   isCompactionNeeded({projectRoot, now, dailyTtlMs?, weeklyTtlMs?})
+//     → {verdict, cronStale, heartbeatAge}
+//        verdict: 'fresh' | 'stale-now' | 'stale-daily' | 'stale-weekly'
+//               | 'cron-active' | 'no-context-dir'
+//        cronStale: boolean   — a cron IS registered but its heartbeat is stale
+//        heartbeatAge: number|null — ms since the last cron run, null if no cron
+//
+//   recordCronHeartbeat({projectRoot, now})  — the ONLY writer; the cron bins
+//     (cmk-daily-distill / cmk-weekly-curate) call it on each fire so the gate
+//     keys off "a run HAPPENED recently" (age), not "a scheduler is registered"
+//     (existence). The anacron model — see docs/research/2026-06-25-cron-liveness.
+//
+// Marker-vs-derive = HYBRID (Q2; the GNU make "Empty Target Files" rule): the
+// now/daily/weekly verdicts are DERIVED from the artifacts the work already
+// rewrites (now.md content, recent.md mtime, today-*.md dates — no new marker,
+// ADR-0002); only cron-liveness gets a stamp, because no artifact expresses "is
+// the background scheduler alive".
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const DEFAULT_DAILY_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+export const DEFAULT_WEEKLY_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+// The cron heartbeat is considered alive within ~2× the daily cron interval
+// (the anacron model: a registered cron that hasn't run in 2 days is dead — the
+// machine was asleep, the registration silently failed, etc.). 2× the 24h daily
+// cadence gives one full grace period before the lazy roll takes over.
+export const DEFAULT_HEARTBEAT_TTL_MS = 2 * DEFAULT_DAILY_TTL_MS; // 48 hours
+
+const SESSIONS_REL = ['context', 'sessions'];
+const NOW_MD_REL = ['context', 'sessions', 'now.md'];
+const RECENT_MD_REL = ['context', 'sessions', 'recent.md'];
+const HEARTBEAT_REL = ['context', '.locks', 'cron-heartbeat'];
+
+const TODAY_RE = /^today-(\d{4}-\d{2}-\d{2})\.md$/;
+
+/**
+ * Path to the cron-heartbeat stamp. Public so register-crons.mjs + the cron bins
+ * can write it without re-deriving the path.
+ */
+export function cronHeartbeatPath(projectRoot) {
+  return join(projectRoot, ...HEARTBEAT_REL);
+}
+
+/**
+ * Record that the scheduled cron actually RAN (the anacron stamp). The ONLY
+ * writer of the heartbeat — called by the cron bins on each fire (success OR
+ * benign no-op; "ran and did nothing" still proves the cron is alive). Best-effort
+ * + atomic-enough (mkdir then touch); mtime is the load-bearing signal.
+ */
+export function recordCronHeartbeat({ projectRoot, now }) {
+  if (!projectRoot) return;
+  const marker = cronHeartbeatPath(projectRoot);
+  mkdirSync(dirname(marker), { recursive: true });
+  if (!existsSync(marker)) {
+    writeFileSync(marker, '', 'utf8');
+  }
+  const ts = new Date(now ?? Date.now());
+  try {
+    utimesSync(marker, ts, ts);
+  } catch {
+    // utimes can fail on exotic filesystems; existence + a write timestamp are
+    // the load-bearing signal, and writeFileSync already stamped it on create.
+  }
+}
+
+/** ms since the cron last ran, or null if no cron heartbeat exists. */
+function heartbeatAgeMs(projectRoot, nowMs) {
+  const marker = cronHeartbeatPath(projectRoot);
+  if (!existsSync(marker)) return null;
+  try {
+    return nowMs - statSync(marker).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function nowMdHasContent(projectRoot) {
+  const p = join(projectRoot, ...NOW_MD_REL);
+  if (!existsSync(p)) return false;
+  try {
+    return readFileSync(p, 'utf8').trim() !== '';
+  } catch {
+    return false;
+  }
+}
+
+function recentMdMtimeMs(projectRoot) {
+  const p = join(projectRoot, ...RECENT_MD_REL);
+  if (!existsSync(p)) return null;
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function listTodayFiles(projectRoot) {
+  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
+  if (!existsSync(sessionsDir)) return [];
+  const matches = [];
+  for (const name of readdirSync(sessionsDir)) {
+    const m = TODAY_RE.exec(name);
+    if (!m) continue;
+    matches.push({ name, date: m[1], path: join(sessionsDir, name) });
+  }
+  return matches;
+}
+
+/**
+ * The deep read: does memory need compacting, and is the cron alive?
+ *
+ * Verdict precedence (Q2): no-context-dir > stale-now > cron-active(fresh) >
+ * stale-weekly > stale-daily > fresh. Note 'cron-active' NO LONGER short-circuits
+ * above the bloat check — a stale-now (un-rolled prior-session content) ALWAYS
+ * wins, because correctness > deferring to a possibly-dead cron ("we're in the
+ * memory business", Q4). Only a FRESH cron defers the derived daily/weekly work.
+ */
+export function isCompactionNeeded({
+  projectRoot,
+  now,
+  dailyTtlMs = DEFAULT_DAILY_TTL_MS,
+  weeklyTtlMs = DEFAULT_WEEKLY_TTL_MS,
+  heartbeatTtlMs = DEFAULT_HEARTBEAT_TTL_MS,
+} = {}) {
+  const nowMs = new Date(now ?? Date.now()).getTime();
+
+  if (!projectRoot) {
+    return { verdict: 'no-context-dir', reason: 'missing-project-root', cronStale: false, heartbeatAge: null };
+  }
+
+  // Cron liveness — by AGE, never existence (the 167.A fix). A registered cron
+  // whose heartbeat is older than the TTL is DEAD; treat it as no cron so the
+  // lazy roll takes over.
+  const hbAge = heartbeatAgeMs(projectRoot, nowMs);
+  const cronRegistered = hbAge !== null;
+  const cronAlive = cronRegistered && hbAge < heartbeatTtlMs;
+  const cronStale = cronRegistered && !cronAlive;
+
+  const base = { cronStale, heartbeatAge: hbAge };
+
+  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
+  if (!existsSync(sessionsDir)) {
+    return { verdict: 'no-context-dir', reason: 'sessions-dir-missing', ...base };
+  }
+
+  // stale-now wins over cron-active (Q4): un-rolled now.md content must drain
+  // THIS session regardless of whether a (possibly dead, possibly alive) cron is
+  // registered — the correctness-over-deferral rule.
+  if (nowMdHasContent(projectRoot)) {
+    return { verdict: 'stale-now', reason: 'now-md-has-prior-session-content', ...base };
+  }
+
+  // A LIVE cron owns the remaining (daily/weekly) levels — defer to it.
+  if (cronAlive) {
+    return { verdict: 'cron-active', reason: 'cron-heartbeat-fresh', ...base };
+  }
+
+  const files = listTodayFiles(projectRoot);
+
+  // Weekly: any today-*.md older than weeklyTtlMs by its date stamp.
+  const weeklyCutoffMs = nowMs - weeklyTtlMs;
+  const hasOldToday = files.some((f) => {
+    const fileMs = new Date(f.date + 'T00:00:00Z').getTime();
+    return Number.isFinite(fileMs) && fileMs < weeklyCutoffMs;
+  });
+  if (hasOldToday) {
+    return { verdict: 'stale-weekly', reason: 'today-file-older-than-7d', ...base };
+  }
+
+  // No today files at all → nothing to compress → fresh (Task 36 I1).
+  if (files.length === 0) {
+    return { verdict: 'fresh', reason: 'no-input', ...base };
+  }
+
+  // Daily: recent.md missing OR older than dailyTtlMs.
+  const mtimeMs = recentMdMtimeMs(projectRoot);
+  if (mtimeMs === null) {
+    return { verdict: 'stale-daily', reason: 'recent-md-missing', ...base };
+  }
+  if (nowMs - mtimeMs > dailyTtlMs) {
+    return { verdict: 'stale-daily', reason: 'recent-md-older-than-ttl', ...base };
+  }
+  return { verdict: 'fresh', reason: 'within-ttl', ...base };
+}

package/src/config-core.mjs

@@ -96,7 +96,21 @@ function coerce(raw) {
   return raw;
 }
 
-function setDeep(obj, dottedKey, value) {
+// Exported for a direct unit test: this guard holds a security invariant
+// (prototype-pollution resistance) and is analyzed by CodeQL in isolation, so
+// it's tested at its own boundary, not only through configSet.
+export function setDeep(obj, dottedKey, value) {
+  // Defense-in-depth: refuse prototype-polluting segments INSIDE the walker
+  // itself, not only at the public entry points (configGet/Set/ShowOrigin all
+  // pre-check via hasForbiddenSegment). A self-guarding utility stays safe even
+  // if a future caller forgets the guard — and it closes the CodeQL
+  // js/prototype-pollution-utility finding. Reuses the same helper as the entry
+  // points so the forbidden-segment set can't drift.
+  if (hasForbiddenSegment(dottedKey)) {
+    throw new Error(
+      `setDeep: forbidden key segment (${[...FORBIDDEN_KEYS].join('/')}) — prototype-pollution guard`,
+    );
+  }
   const parts = dottedKey.split('.');
   let cur = obj;
   for (let i = 0; i < parts.length - 1; i++) {

package/src/doctor.mjs

@@ -43,6 +43,7 @@ import { basename, join } from 'node:path';
 import { nowIso } from './audit-log.mjs';
 import { detectStaleLocks } from './lock-discipline.mjs';
 import { cronSentinelPath } from './lazy-compress.mjs';
+import { isCompactionNeeded } from './compaction-state.mjs';
 import { getNativeAutoMemoryState } from './native-memory.mjs';
 import { checkKitBinding, checkEmbedderBinding } from './native-binding.mjs';
 import { resolveDefaultSearchMode } from './semantic-backend.mjs';
@@ -640,6 +641,45 @@ function hc9VersionDrift({ projectRoot, kitVersion }) {
   return checkVersionDrift({ claudeMdText, kitVersion });
 }
 
+// --- HC-10: Scheduled compaction liveness (Task 167 / D-207) ----------
+// INFORMATIONAL — memory self-heals automatically every session (the lazy roll
+// is the floor, 167.A/D), so a dead cron is a degraded OPTIMIZATION, not data
+// loss. NEVER prescribes a manual heal (no recoveryCommand). A DEV/diagnostic
+// aid (it surfaced THIS bug class) + a heads-up for a power user. SKIPs when no
+// cron is registered (the default) — the lazy roll covers compaction there.
+function hc10CompactionLiveness({ projectRoot, now }) {
+  const v = isCompactionNeeded({ projectRoot, now });
+  // No cron registered (heartbeatAge null) → nothing to check; the lazy roll owns
+  // compaction. SKIP (consistent with HC-5's optional-cron posture).
+  if (v.heartbeatAge === null) {
+    return {
+      id: 'HC-10',
+      name: 'Scheduled compaction is alive',
+      status: 'skip',
+      message: 'no scheduled cron registered (optional) — memory self-heals each session via the lazy roll.',
+    };
+  }
+  if (v.cronStale) {
+    const days = Math.floor(v.heartbeatAge / (24 * 60 * 60 * 1000));
+    return {
+      id: 'HC-10',
+      name: 'Scheduled compaction is alive',
+      status: 'fail',
+      // Informational framing — NO recoveryCommand. The kit self-heals; this is a
+      // heads-up that the OPTIONAL nightly schedule isn't firing (asleep at 23:00,
+      // a registration that didn't take catch-up). Re-running register-crons is a
+      // user choice, not a required repair.
+      message: `your scheduled compaction looks dead (last ran ~${days}d ago) — memory still self-heals automatically each session, so no action is needed; run \`cmk register-crons\` only if you want the nightly schedule back.`,
+    };
+  }
+  return {
+    id: 'HC-10',
+    name: 'Scheduled compaction is alive',
+    status: 'pass',
+    message: 'scheduled compaction heartbeat is fresh',
+  };
+}
+
 export async function runDoctor({
   projectRoot,
   userDir,
@@ -672,10 +712,11 @@ export async function runDoctor({
   const c8 = await hc8NativeBindings({ projectRoot, kitBindingProbe, embedderBindingProbe });
   // HC-9: kitVersion injectable for tests; defaults to the installed binary's version.
   const c9 = hc9VersionDrift({ projectRoot, kitVersion: kitVersion ?? getKitVersion() });
+  const c10 = hc10CompactionLiveness({ projectRoot, now: ts });
 
   return {
     action: 'completed',
-    checks: [c1, c2, c3, c4, c5, c6, c7, c8, c9],
+    checks: [c1, c2, c3, c4, c5, c6, c7, c8, c9, c10],
     duration_ms: Date.now() - t0,
   };
 }

package/src/inject-context.mjs

@@ -34,7 +34,7 @@ import { spawn } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
-import { SCRATCHPADS_BY_TIER, resolveTierRoot, ID_PATTERN } from './tier-paths.mjs';
+import { SCRATCHPADS_BY_TIER, resolveTierRoot, ID_PATTERN, discoverRootUpward } from './tier-paths.mjs';
 import { nowIso } from './audit-log.mjs';
 import { detectStaleness, isJournalStale } from './lazy-compress.mjs';
 import { isProvenanceCommentLine, parseBulletProvenance } from './provenance.mjs';
@@ -171,21 +171,14 @@ function latestDaySession(sessionsDir) {
 // kit's project-tier root convention is `<repo>/context/`; the walk-up
 // matches `git rev-parse --show-toplevel`'s semantics for nested invocations
 // (a hook may fire while Claude Code's cwd is in a sub-package).
+// Task 168: discovery walks up to the nearest project root, recognizing EITHER
+// tier directory — `context/` (committed) OR `context.local/` (gitignored local)
+// — so a local-only project resolves correctly, and STOPPING at the home dir so a
+// stray `~/context/` can't hijack discovery from an unrelated subdir. Shares the
+// single `discoverRootUpward` implementation with resolveMcpProjectRoot (one
+// home-boundary + canonicalize algorithm, no drift across the two walkers).
 function discoverProjectRoot(cwd) {
-  let dir = cwd;
-  // Defensive bound: walk no more than 64 ancestors.
-  for (let i = 0; i < 64; i++) {
-    if (existsSync(join(dir, 'context'))) return dir;
-    const parent = join(dir, '..');
-    const norm = statSync(parent).isDirectory() ? parent : null;
-    if (!norm || norm === dir) break;
-    // Stop at the filesystem root.
-    if (/^[A-Za-z]:\\?$|^\/$/.test(dir)) break;
-    dir = parent;
-  }
-  // Fall back to `cwd` — the per-tier readers will return empty for
-  // absent dirs, so this stays safe.
-  return cwd;
+  return discoverRootUpward(cwd, ['context', 'context.local']);
 }
 
 function tierDirExists(tier, tierRoot) {

package/src/install.mjs

@@ -494,7 +494,12 @@ export async function install(options = {}) {
   // the pin-off; checked first below).
   let semantic = { action: 'skipped' };
   if (options.withSemantic) {
-    semantic = await enableSemantic({ projectRoot, spawnNpm: options.spawnNpm, warm: options.warmEmbedder });
+    semantic = await enableSemantic({
+      projectRoot,
+      spawnNpm: options.spawnNpm,
+      warm: options.warmEmbedder,
+      probeEmbedder: options.probeEmbedder,
+    });
     if (semantic.action === 'error') errors.push({ path: 'semantic', error: semantic.error });
   } else if (options.noSemantic) {
     const r = mergeProjectSettings(projectRoot, { search: { default_mode: 'keyword' } });
@@ -571,15 +576,43 @@ export function buildDefaultNpmRunner({ spawnSyncImpl = spawnSync } = {}) {
   };
 }
 
-async function enableSemantic({ projectRoot, spawnNpm, warm }) {
+async function enableSemantic({ projectRoot, spawnNpm, warm, probeEmbedder }) {
   // 1. Install the optional embedder globally (it resolves as a sibling of
   // the globally-installed kit). Injectable for tests.
   const runNpm = spawnNpm ?? buildDefaultNpmRunner();
   const npm = runNpm();
-  if (npm.status !== 0) {
+
+  // Task 170 (the v0.4.1 cut-gate find): gate on whether the embedder ACTUALLY
+  // IMPORTS, NOT on npm's exit code — verify the thing worked, not the command's
+  // exit (the D-199 class). Two failure modes the exit code gets wrong, BOTH
+  // sides:
+  //   - npm exits NON-ZERO but the package installed fine: on Windows a benign
+  //     cleanup-EBUSY (npm failing to unlink a leftover temp DLL still locked by
+  //     a running process — sharp-win32-x64 / libvips) makes npm exit non-zero
+  //     AFTER a successful install. Trusting the exit FALSELY reported "NOT
+  //     enabled" while the embedder was present + importable (the live find).
+  //   - npm exits ZERO but the import is BROKEN (partial/corrupt native module):
+  //     trusting the exit would wrongly write a hybrid default with no working
+  //     embedder — every search would degrade to the fallback warning (the
+  //     half-state this function exists to avoid).
+  // So PROBE the import once, and enable hybrid IFF it imports — regardless of
+  // npm's exit. The install must be AUTOMATIC: the user does nothing and never
+  // needs a manual `cmk config set` to recover from a benign npm warning.
+  const probe = probeEmbedder ?? (async () => {
+    const { checkEmbedderBinding } = await import('./native-binding.mjs');
+    return checkEmbedderBinding();
+  });
+  let imported;
+  try {
+    imported = await probe();
+  } catch {
+    imported = { ok: false };
+  }
+  if (!imported?.ok) {
+    const detail = npm.status !== 0 ? (npm.error ?? `exit ${npm.status}`) : (imported?.reason ?? 'embedder import failed');
     return {
       action: 'error',
-      error: `npm install -g @huggingface/transformers failed (${npm.error ?? `exit ${npm.status}`}) — semantic recall NOT enabled; keyword search is unaffected`,
+      error: `semantic embedder not usable after install (${detail}) — semantic recall NOT enabled; keyword search is unaffected`,
     };
   }
   // 2. Flip the project default to hybrid ONLY after the dependency landed

package/src/lazy-compress.mjs

@@ -29,9 +29,7 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
-  readFileSync,
   statSync,
-  writeFileSync,
   unlinkSync,
 } from 'node:fs';
 import { join } from 'node:path';
@@ -46,44 +44,58 @@ import { weeklyCurate } from './weekly-curate.mjs';
 import { compressSession } from './compress-session.mjs';
 import { CEILING_FREE_TIMEOUT_MS, CEILING_FREE_BACKOFF_MS } from './compress-retry.mjs';
 import { syncDecisionsJournal } from './decisions-journal.mjs';
+import {
+  isCompactionNeeded,
+  recordCronHeartbeat,
+  cronHeartbeatPath,
+} from './compaction-state.mjs';
 
 const DEFAULT_DAILY_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
 const DEFAULT_WEEKLY_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
-const SESSIONS_REL = ['context', 'sessions'];
 const LOCKS_REL = ['context', '.locks'];
-const NOW_MD_REL = ['context', 'sessions', 'now.md'];
-const RECENT_MD_REL = ['context', 'sessions', 'recent.md'];
-const CRON_SENTINEL_REL = ['context', '.locks', 'cron-registered'];
 const LAZY_LOG_REL = ['context', '.locks', 'lazy-compress.log'];
 
-const TODAY_RE = /^today-(\d{4}-\d{2}-\d{2})\.md$/;
+// Task 167 (D-206/D-207): the cron-liveness gate moved from a presence-only
+// `cron-registered` sentinel to an anacron-style `cron-heartbeat` (in
+// compaction-state.mjs), gated on AGE not existence — a registered-but-dead cron
+// no longer disables the lazy roll. These three exports are kept as thin
+// back-compat shims so existing callers (register-crons / doctor / subcommands /
+// tests) keep working; they now operate on the heartbeat.
+//
+// **Decision-trail (the retired sentinel):** the old `cron-registered` marker
+// recorded "a cron was REGISTERED" (written once at register-crons time, never
+// updated). detectStaleness short-circuited to 'cron-active' on its mere
+// existence — so a cron that never actually fired (laptop asleep at 23:00)
+// disabled the lazy fallback forever and now.md grew to 410 KB (the v0.4.0
+// dogfood). The heartbeat records "a run HAPPENED" and is re-stamped each fire.
 
 /**
- * Path helper for the cron-registered sentinel marker file. Public so
- * register-crons.mjs can write/remove it without re-deriving the path.
+ * Back-compat alias for the cron-liveness marker path. Now points at the
+ * `cron-heartbeat` stamp (was `cron-registered`). Retained for callers that still
+ * import it; prefer `cronHeartbeatPath` from compaction-state.mjs in new code.
  */
 export function cronSentinelPath(projectRoot) {
-  return join(projectRoot, ...CRON_SENTINEL_REL);
+  return cronHeartbeatPath(projectRoot);
 }
 
 /**
- * Write the cron-registered sentinel marker. Called by registerCron
- * after a successful host-scheduler registration.
+ * Record that the cron is alive. Now writes the anacron-style heartbeat (was: a
+ * one-time registration sentinel). `register-crons` calls it on registration so a
+ * just-registered cron reads alive until its first real run re-stamps it; the
+ * cron BINS also call `recordCronHeartbeat` on each fire (the durable liveness
+ * signal). Both go to the same stamp.
  */
 export function markCronRegistered({ projectRoot }) {
-  if (!projectRoot) return;
-  const locksDir = join(projectRoot, ...LOCKS_REL);
-  mkdirSync(locksDir, { recursive: true });
-  writeFileSync(cronSentinelPath(projectRoot), nowIso() + '\n', 'utf8');
+  recordCronHeartbeat({ projectRoot });
 }
 
 /**
- * Remove the cron-registered sentinel marker. Called by unregisterCron.
- * Best-effort — if the marker is missing, that's already the desired state.
+ * Remove the cron-liveness heartbeat (on unregister). Best-effort — a missing
+ * stamp is already the desired "no live cron" state.
  */
 export function unmarkCronRegistered({ projectRoot }) {
   if (!projectRoot) return;
-  const path = cronSentinelPath(projectRoot);
+  const path = cronHeartbeatPath(projectRoot);
   if (existsSync(path)) {
     try {
       unlinkSync(path);
@@ -93,18 +105,6 @@ export function unmarkCronRegistered({ projectRoot }) {
   }
 }
 
-function listTodayFiles(projectRoot) {
-  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
-  if (!existsSync(sessionsDir)) return [];
-  const matches = [];
-  for (const name of readdirSync(sessionsDir)) {
-    const m = TODAY_RE.exec(name);
-    if (!m) continue;
-    matches.push({ name, date: m[1], path: join(sessionsDir, name) });
-  }
-  return matches;
-}
-
 // Task 105 (D-75): does now.md carry prior-session content? The now→today
 // roll (compressSession) fires only at SessionEnd, and Claude Code fires
 // SessionEnd ONLY on a clean window-close — so a never-cleanly-closed session
@@ -114,25 +114,10 @@ function listTodayFiles(projectRoot) {
 // capture-turn writes haven't fired yet), so non-empty ⇒ stale. Emptiness must
 // match compressSession's own `buffer.trim() === ''` check so the spawn verdict
 // and the actual roll agree (else we'd spawn for a roll that immediately skips).
-function nowMdHasContent(projectRoot) {
-  const p = join(projectRoot, ...NOW_MD_REL);
-  if (!existsSync(p)) return false;
-  try {
-    return readFileSync(p, 'utf8').trim() !== '';
-  } catch {
-    return false;
-  }
-}
-
-function recentMdMtimeMs(projectRoot) {
-  const p = join(projectRoot, ...RECENT_MD_REL);
-  if (!existsSync(p)) return null;
-  try {
-    return statSync(p).mtimeMs;
-  } catch {
-    return null;
-  }
-}
+// Task 167 (D-207): nowMdHasContent / recentMdMtimeMs / listTodayFiles + the
+// now/daily/weekly derive logic moved to compaction-state.mjs (the deep module
+// that owns the verdict). detectStaleness now delegates there; only isJournalStale
+// (an INDEPENDENT signal, not part of the compaction verdict) stays here.
 
 const MEMORY_REL = ['context', 'memory'];
 const DECISIONS_MD_REL = ['context', 'DECISIONS.md'];
@@ -210,66 +195,14 @@ export function detectStaleness({
   dailyTtlMs = DEFAULT_DAILY_TTL_MS,
   weeklyTtlMs = DEFAULT_WEEKLY_TTL_MS,
 } = {}) {
-  if (!projectRoot) {
-    return { action: 'no-context-dir', reason: 'missing-project-root' };
-  }
-  // Cron sentinel short-circuits everything.
-  if (existsSync(cronSentinelPath(projectRoot))) {
-    return { action: 'cron-active', reason: 'cron-sentinel-present' };
-  }
-  const sessionsDir = join(projectRoot, ...SESSIONS_REL);
-  if (!existsSync(sessionsDir)) {
-    return { action: 'no-context-dir', reason: 'sessions-dir-missing' };
-  }
-
-  // Task 105 (D-75): a non-empty now.md is the now→today roll the SessionEnd
-  // hook would have done. It takes PRECEDENCE over daily/weekly because it's
-  // the FIRST pipeline level (now → today → recent → archive) — roll it this
-  // SessionStart; the today→recent + weekly levels cascade on subsequent
-  // SessionStarts once now.md is drained. (cron-active above still wins — a
-  // registered cron owns the whole pipeline.)
-  if (nowMdHasContent(projectRoot)) {
-    return { action: 'stale-now', reason: 'now-md-has-prior-session-content' };
-  }
-
-  const ts = now ?? nowIso();
-  const nowMs = new Date(ts).getTime();
-  const files = listTodayFiles(projectRoot);
-
-  // Weekly check: any today-*.md older than weeklyTtlMs by its date stamp
-  // (NOT mtime — the file's date is the canonical age signal; mtime can
-  // drift if someone touched the file).
-  const weeklyCutoffMs = nowMs - weeklyTtlMs;
-  const hasOldToday = files.some((f) => {
-    const fileMs = new Date(f.date + 'T00:00:00Z').getTime();
-    return Number.isFinite(fileMs) && fileMs < weeklyCutoffMs;
-  });
-  if (hasOldToday) {
-    return { action: 'stale-weekly', reason: 'today-file-older-than-7d' };
-  }
-
-  // Task 36 I1 fix: if there are NO today-*.md files at all, the
-  // pipeline has nothing to compress — return fresh regardless of
-  // recent.md mtime. Previously this check only fired when recent.md
-  // was MISSING; for the stale-but-no-input case (e.g., right after
-  // weeklyCurate archived every today file), the daily-stale branch
-  // would fire and the SessionStart hook would spawn lazy-compress
-  // forever (no new today file means no work; dailyDistill would
-  // return skipped:no-input but not touch recent.md, so the next
-  // SessionStart sees the same stale verdict).
-  if (files.length === 0) {
-    return { action: 'fresh', reason: 'no-input' };
-  }
-
-  // Daily check: recent.md missing OR older than dailyTtlMs.
-  const mtimeMs = recentMdMtimeMs(projectRoot);
-  if (mtimeMs === null) {
-    return { action: 'stale-daily', reason: 'recent-md-missing' };
-  }
-  if (nowMs - mtimeMs > dailyTtlMs) {
-    return { action: 'stale-daily', reason: 'recent-md-older-than-ttl' };
-  }
-  return { action: 'fresh', reason: 'within-ttl' };
+  // Task 167 (D-207): delegate to the compaction-state deep module. This is a
+  // thin back-compat adapter — it maps the rich `{verdict, cronStale,
+  // heartbeatAge}` return onto the legacy `{action, reason}` shape callers
+  // (inject-context, runLazyCompress) already consume. The KEY behavior change
+  // vs the old body: `cron-active` is now gated on heartbeat FRESHNESS (age), not
+  // sentinel existence, so a dead cron falls through to the stale verdicts.
+  const r = isCompactionNeeded({ projectRoot, now, dailyTtlMs, weeklyTtlMs });
+  return { action: r.verdict, reason: r.reason, cronStale: r.cronStale, heartbeatAge: r.heartbeatAge };
 }
 
 function writeLazyLogEntry({ projectRoot, entry }) {

package/src/register-crons.mjs

@@ -303,6 +303,37 @@ export function registerCron(opts = {}) {
     // schtasks path + the verbatim argv). Production never passes it.
     const spawn = opts.spawn ?? spawnSync;
     const r = spawn(schtasksExe, argv, { encoding: 'utf8', windowsHide: true, timeout: 10_000 });
+
+    // Task 167.E (D-207): set StartWhenAvailable so a missed nightly run (laptop
+    // asleep at 23:00) runs on wake instead of being silently dropped. schtasks
+    // /Create has NO CLI flag for this (verified — not in the help); it's settable
+    // only via XML or PowerShell. We use a follow-up PowerShell Set-ScheduledTask,
+    // BEST-EFFORT: a failure here never fails registration — the lazy roll
+    // (167.A/D) is the guarantee; this is a catch-up OPTIMIZATION. NB: this only
+    // covers a missed run while the machine is OFF/asleep; all OS catch-up
+    // mechanisms COALESCE multiple missed periods into one run (research note).
+    if (r.status === 0) {
+      const psExe = join(
+        process.env.SystemRoot || process.env.windir || 'C:\\Windows',
+        'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe',
+      );
+      const psScript =
+        `try { Set-ScheduledTask -TaskName '${entryName}' ` +
+        `-Settings (New-ScheduledTaskSettingsSet -StartWhenAvailable) ` +
+        `-ErrorAction Stop | Out-Null } catch { exit 1 }`;
+      try {
+        spawn(psExe, ['-NoProfile', '-NonInteractive', '-Command', psScript], {
+          encoding: 'utf8',
+          windowsHide: true,
+          timeout: 10_000,
+        });
+        // We intentionally ignore the PS exit status — registration already
+        // succeeded; catch-up is best-effort.
+      } catch {
+        // never let the catch-up call abort a successful registration
+      }
+    }
+
     return {
       action: r.status === 0 ? 'registered' : 'error',
       platform,