sweet-search 2.5.2 → 2.5.3

package/core/indexing/index-maintainer.mjs

@@ -7,7 +7,7 @@
  *
  * Features:
  * - Deferred merkle check (7s delay, ZERO startup latency)
- * - 45-second periodic merkle check (mtime/size fast-path)
+ * - 45-second periodic merkle check (mtime/size/inode fast-path)
  * - Full incremental index: FTS5, HNSW, Binary HNSW, Code Graph (full), HCGS
  * - Global lock file prevents race with manual /index-codebase
  * - Soft delete for removed files (handles branch switches, prune after 30d)
@@ -37,11 +37,16 @@
  * Started by: session-preheat.sh (alongside search infrastructure)
  */
 
-import { readFileSync, writeFileSync, existsSync, unlinkSync, renameSync, appendFileSync, mkdirSync, openSync, closeSync, constants } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, renameSync, appendFileSync, mkdirSync, openSync, closeSync, constants, ftruncateSync, fsyncSync, writeSync } from 'node:fs';
 import fs from 'node:fs/promises';
-import { dirname, join, relative, isAbsolute } from 'node:path';
+import { dirname, join, relative, isAbsolute, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { startupInterval, tierForHardware, reconcileEnablement } from '../incremental-indexing/domain/interval-autotune.mjs';
+import { detectHardwareCapability } from '../infrastructure/hardware-capability.js';
+import { sweepStaleArtifactTemps, DEFAULT_TMP_SWEEP_MAX_AGE_MS } from '../incremental-indexing/infrastructure/artifact-temp-sweep.mjs';
+import { hasCompleteBaseIndex, WAITING_FOR_INITIAL_INDEX } from '../incremental-indexing/infrastructure/baseline-readiness.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -149,6 +154,7 @@ const QUEUE_FILE = join(DATA_DIR, 'index-maintainer-queue.jsonl');
 const PROCESSING_FILE = join(DATA_DIR, 'index-maintainer-queue.processing.jsonl');
 const LOCK_FILE = join(DATA_DIR, 'index-maintainer.lock');
 const DEADLETTER_FILE = join(DATA_DIR, 'index-maintainer-deadletter.jsonl');
+const PAUSE_FILE = join(DATA_DIR, 'reconcile-pause.json');
 
 // Export configuration for testing
 export const CONFIG = {
@@ -158,6 +164,7 @@ export const CONFIG = {
   PROCESSING_FILE,
   LOCK_FILE,
   DEADLETTER_FILE,
+  PAUSE_FILE,
 };
 
 // Indexer paths
@@ -251,6 +258,40 @@ async function loadBetterSqlite3() {
 const POLL_INTERVAL = 30000;           // 30 seconds between queue checks
 const LOCK_REFRESH_INTERVAL = 30000;   // 30 seconds between lock refreshes (M5: was 60s)
 const LOCK_STALE_THRESHOLD = 180000;   // 3 minutes (M5: was 5 min, ratio 6:1 with refresh)
+// Lifecycle fix v2 — progress-aware takeover. The legacy 3-min pure-timestamp
+// takeover ("lock looks stale ⇒ steal it") produced stealth co-owner orphans
+// when a busy daemon's heartbeat aged past the threshold; the v1 interim fix
+// raised the threshold to 30 min, which traded faster wedge recovery for
+// safety. v2 reverts the threshold to 3 min and adds a second signal so we
+// keep both: orphan-free AND fast recovery, without false-positives on long
+// async work.
+//
+// The lockfile now carries TWO timestamps:
+//   - `timestamp`         — the heartbeat, refreshed every 30 s by setInterval
+//                           (event-loop bound, like before).
+//   - `progressTimestamp` — refreshed by recordProgress() at known work
+//                           checkpoints inside the reconcile loop.
+//
+// acquireStateLock combines them:
+//
+//   heartbeat fresh AND progress fresh   → busy + progressing → REFUSE
+//   heartbeat fresh AND progress stale   → alive-but-stuck    → SIGTERM + steal
+//   heartbeat stale AND progress fresh   → recent progress    → REFUSE (timer lag)
+//   heartbeat stale AND progress stale   → genuinely wedged   → SIGTERM + steal
+//   dead pid                             → crashed            → immediate takeover
+//
+// Backwards-compat: a lockfile without `progressTimestamp` falls back to
+// heartbeat-only (progressAge := heartbeatAge), reverting to classic 3-min
+// behaviour. The SIGTERM-before-steal hardening means even this legacy path
+// never leaks orphans.
+//
+// Caveat: progress IS still recorded from the main event loop, so a daemon
+// blocked by pure synchronous CPU/native work shows both signals stale and
+// will be SIGTERMed at 3 min. With async napi (see
+// project_native_metal_inference_status) this case should not arise in
+// practice; the natural escalation if it does is a worker_threads-based
+// progress beacon — left as future work.
+export const WEDGED_KILL_GRACE_MS = 5000;  // SIGTERM grace before declaring takeover complete
 
 // Retry configuration
 const MAX_RETRIES = 3;
@@ -526,6 +567,620 @@ export function ensureDataDir() {
   }
 }
 
+export function isReconcilePaused(stateDir = DATA_DIR) {
+  const pauseFile = join(stateDir, 'reconcile-pause.json');
+  try {
+    const payload = JSON.parse(readFileSync(pauseFile, 'utf-8'));
+    return {
+      paused: payload?.paused !== false,
+      pausedAt: payload?.pausedAt || null,
+      reason: payload?.reason || null,
+      filePath: pauseFile,
+    };
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      log('WARN', `Ignoring unreadable reconcile pause state: ${err.message}`);
+    }
+    return { paused: false, filePath: pauseFile };
+  }
+}
+
+/**
+ * Full enablement status for the reconcile-v2 incremental indexer. Delegates
+ * to the incremental-indexing domain policy (`reconcileEnablement`) so the
+ * daemon and the operator `status` surface share one source of truth.
+ *
+ * Default-on: a missing/empty `SWEET_SEARCH_RECONCILE_V2` means enabled. Opt
+ * out with `0` / `false` / `off`.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{enabled:boolean, source:string, raw:string|null}}
+ */
+export function reconcileV2Status(env = process.env) {
+  return reconcileEnablement(env);
+}
+
+export function reconcileV2Requested(env = process.env) {
+  return reconcileEnablement(env).enabled;
+}
+
+export function assertReconcileV2NotSilentlyIgnored(env = process.env) {
+  if (!reconcileV2Requested(env)) return;
+}
+
+function reconcileV2Context(env = process.env) {
+  const projectRoot = resolve(env.SWEET_SEARCH_PROJECT_ROOT || PROJECT_ROOT);
+  const stateDir = resolve(env.SWEET_SEARCH_STATE_DIR || join(projectRoot, '.sweet-search'));
+  return { projectRoot, stateDir };
+}
+
+/**
+ * Resolve the reconcile-v2 tick interval at daemon startup.
+ *
+ * Delegates to `startupInterval` in the incremental-indexing domain so the
+ * daemon path and the domain module share the same env precedence and
+ * hardware-tier semantics. The hardware capability is detected lazily and
+ * passed in; explicit `tier` overrides via `opts.tier` short-circuit it.
+ *
+ * @param {{env?:NodeJS.ProcessEnv, hardware?:object, tier?:'low'|'mid'|'high'}} [opts]
+ * @returns {{intervalMs:number, pinned:boolean, source:string, tier:string|null}}
+ */
+export function resolveReconcileV2Interval(opts = {}) {
+  const env = opts.env || process.env;
+  let hardware = opts.hardware;
+  if (hardware === undefined) {
+    try {
+      hardware = detectHardwareCapability();
+    } catch {
+      hardware = null;
+    }
+  }
+  const tier = opts.tier || (hardware ? tierForHardware(hardware) : null);
+  const result = startupInterval({ tier: tier || undefined, env, hardware });
+  return { ...result, tier };
+}
+
+function reconcileV2IntervalMs(env = process.env) {
+  return resolveReconcileV2Interval({ env }).intervalMs;
+}
+
+function readStateLock(lockFile) {
+  try {
+    const parsed = JSON.parse(readFileSync(lockFile, 'utf-8'));
+    return Number.isInteger(parsed.pid) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Module-level lockfile state — populated by acquireStateLock on success,
+// mutated by writeStateLock (heartbeat tick) AND recordProgress (work
+// checkpoint), cleared by releaseStateLock. Both writers share this object
+// so a heartbeat write never clobbers progress fields and vice-versa.
+let lockState = null;
+
+/**
+ * True iff a parsed state lock belongs to this process's current acquisition.
+ * The ownerToken closes the same-pid / stale-module-state hole in tests and
+ * long-lived hosts; legacy test fixtures without a token still match by pid
+ * when this process has no active token.
+ */
+function lockMatchesCurrentOwner(existing) {
+  if (existing?.pid !== process.pid) return false;
+  if (lockState?.ownerToken) return existing.ownerToken === lockState.ownerToken;
+  return true;
+}
+
+function readStateLockFromFd(fd) {
+  try {
+    const parsed = JSON.parse(readFileSync(fd, 'utf-8'));
+    return Number.isInteger(parsed.pid) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Re-validate ownership through an open fd, mutate the in-memory lockState,
+ * then write back through that same fd. This deliberately avoids temp+rename:
+ * if another daemon unlinks/recreates the path after our open, our write lands
+ * on the old unlinked inode, not on the successor's new lockfile.
+ */
+function persistLockState(lockFile, mutator) {
+  if (!lockState) return;
+  let fd = null;
+  try {
+    fd = openSync(lockFile, constants.O_RDWR);
+    const existing = readStateLockFromFd(fd);
+    if (!lockMatchesCurrentOwner(existing)) return;
+    mutator(lockState);
+    const payload = JSON.stringify(lockState);
+    const bytes = Buffer.from(payload, 'utf-8');
+    ftruncateSync(fd, 0);
+    writeSync(fd, bytes, 0, bytes.length, 0);
+    try { fsyncSync(fd); } catch { /* best-effort durability for heartbeat */ }
+  } catch {
+    // Missing/corrupt/displaced locks are handled by the main ownership check.
+  } finally {
+    if (fd != null) {
+      try { closeSync(fd); } catch {}
+    }
+  }
+}
+
+function writeStateLock(lockFile) {
+  persistLockState(lockFile, (s) => { s.timestamp = Date.now(); });
+}
+
+/**
+ * Lifecycle fix v2 — record a work-progress checkpoint. Called from the
+ * reconcile loop (top of iteration, post-tick, post-drain) so a candidate
+ * maintainer in acquireStateLock can tell "alive but stuck on a hung await"
+ * from "busy and progressing." One small JSON write per call; the cost is
+ * negligible at the call frequencies we use (≈ once per loop iteration).
+ *
+ * Designed for the main thread (single event loop). If the event loop is
+ * fully blocked by synchronous native work, neither this nor writeStateLock
+ * fires and both signals stale together — that case is intentionally treated
+ * as "wedged" and SIGTERMed (with the queue-based recovery making lost work
+ * idempotent). For a fully event-loop-independent signal a worker_threads
+ * beacon would be the next step.
+ */
+export function recordProgress(lockFile) {
+  persistLockState(lockFile, (s) => {
+    s.progressCounter = (s.progressCounter ?? 0) + 1;
+    s.progressTimestamp = Date.now();
+  });
+}
+
+/**
+ * SIGTERM the previous holder and unlink the lockfile, after a bounded grace
+ * period. Shared by both takeover branches in acquireStateLock (alive-but-
+ * stuck AND fully wedged). The dying holder exits via its SIGTERM handler;
+ * if it can't (uninterruptible syscall), its in-loop `stillOwnsLock` check
+ * ends it gracefully when it eventually unblocks. Either way: no immortal
+ * twin.
+ */
+async function sigtermAndStealLock(existing, lockFile, reason) {
+  log('WARN', `Existing maintainer pid=${existing.pid} appears ${reason}; sending SIGTERM before takeover.`);
+  try { process.kill(existing.pid, 'SIGTERM'); } catch { /* ESRCH/EPERM — fine, we'll steal anyway */ }
+  const deadline = Date.now() + WEDGED_KILL_GRACE_MS;
+  while (Date.now() < deadline && isPidRunning(existing.pid, existing.startTime)) {
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  if (isPidRunning(existing.pid, existing.startTime)) {
+    log('WARN', `pid=${existing.pid} still alive after SIGTERM+${WEDGED_KILL_GRACE_MS}ms grace; proceeding (it will self-exit at its next loop tick).`);
+  }
+  try { unlinkSync(lockFile); } catch {}
+}
+
+/**
+ * Acquire the reconcile-v2 state lock atomically.
+ *
+ * Lifecycle fix v2 — progress-aware single-owner takeover (see the
+ * WEDGED_KILL_GRACE_MS block above for the design rationale). Decision
+ * matrix on an existing lockfile:
+ *
+ *   no / unparseable lock                  → unlink + retry create
+ *   dead holder                            → unlink + retry create
+ *   alive, heartbeat fresh, progress fresh → REFUSE
+ *   alive, heartbeat stale, progress fresh → REFUSE (timer-lag tolerance)
+ *   alive, heartbeat fresh, progress stale → SIGTERM + steal (alive-but-stuck)
+ *   alive, both stale                      → SIGTERM + steal (wedged)
+ *
+ * Returns { acquired, lockFile }. On successful acquisition, initialises the
+ * module-level `lockState` with both heartbeat and progress timestamps so
+ * the new owner is never "stale" immediately. Async because the
+ * SIGTERM-and-steal path awaits a bounded grace period; the legacy
+ * synchronous form had no caller outside runReconcileV2Main (verified by grep).
+ */
+export async function acquireStateLock(stateDir) {
+  mkdirSync(stateDir, { recursive: true });
+  const lockFile = join(stateDir, 'index-maintainer.lock');
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = openSync(lockFile, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+      // Initialise the in-memory state. progressTimestamp starts equal to
+      // timestamp so a fresh owner is never falsely declared stale on either
+      // signal by a candidate maintainer that races our first tick.
+      const nowMs = Date.now();
+      lockState = {
+        pid: process.pid,
+        timestamp: nowMs,
+        startTime: getProcessStartTime(),
+        ownerToken: randomUUID(),
+        progressCounter: 0,
+        progressTimestamp: nowMs,
+      };
+      writeFileSync(fd, JSON.stringify(lockState));
+      closeSync(fd);
+      return { acquired: true, lockFile };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      const existing = readStateLock(lockFile);
+      if (!existing) {
+        // Corrupt / unparseable lock — unlink and retry the O_EXCL create.
+        try { unlinkSync(lockFile); } catch {}
+        continue;
+      }
+      const holderAlive = isPidRunning(existing.pid, existing.startTime);
+      if (!holderAlive) {
+        // Crashed daemon — safe to reclaim. (Preserves the dead-pid contract
+        // exercised by tests/indexing/maintainer-launcher.test.js.)
+        try { unlinkSync(lockFile); } catch {}
+        continue;
+      }
+      const now = Date.now();
+      const heartbeatAge = now - existing.timestamp;
+      // Backwards-compat: a legacy lockfile without progressTimestamp falls
+      // back to heartbeat-only mode. Combined with SIGTERM-before-steal this
+      // still avoids orphans even for writers that don't know about progress.
+      const progressAge = existing.progressTimestamp != null
+        ? now - existing.progressTimestamp
+        : heartbeatAge;
+      const heartbeatFresh = heartbeatAge < LOCK_STALE_THRESHOLD;
+      const progressFresh = progressAge < LOCK_STALE_THRESHOLD;
+      if (heartbeatFresh && progressFresh) {
+        // Busy AND progressing — single-owner invariant: refuse takeover.
+        return { acquired: false, lockFile };
+      }
+      if (progressFresh) {
+        // Progress recorded recently even though the heartbeat timer lagged
+        // (occasional event-loop pause that swallowed a setInterval tick).
+        // Actual work IS happening — trust the progress signal, refuse.
+        return { acquired: false, lockFile };
+      }
+      const reason = heartbeatFresh
+        ? `alive but not progressing (progress age=${Math.round(progressAge / 1000)}s)`
+        : `wedged (heartbeat age=${Math.round(heartbeatAge / 1000)}s, progress age=${Math.round(progressAge / 1000)}s)`;
+      await sigtermAndStealLock(existing, lockFile, reason);
+    }
+  }
+  return { acquired: false, lockFile };
+}
+
+export function releaseStateLock(lockFile) {
+  try {
+    const existing = readStateLock(lockFile);
+    if (lockMatchesCurrentOwner(existing)) unlinkSync(lockFile);
+  } catch {}
+  // Reset module-level state so a subsequent acquire (in tests, in long-lived
+  // hosts, in respawn paths) starts from a clean slate.
+  lockState = null;
+}
+
+/**
+ * Lifecycle fix. Returns true iff the state lockfile exists AND still names
+ * this process. Used by:
+ *   - the main reconcile loop, to self-exit when displaced (no immortal
+ *     twins after a wedged-backstop takeover), and
+ *   - the heartbeat refresh setInterval, so a displaced daemon never
+ *     clobbers a successor's lock by rewriting its own pid.
+ *
+ * Missing/unparseable lockfile is treated as "not ours" — conservatively
+ * exits the daemon so the launcher can respawn a clean single owner rather
+ * than risk a race during a successor's mid-takeover write.
+ */
+export function stillOwnsLock(lockFile) {
+  const existing = readStateLock(lockFile);
+  if (!existing) return false;
+  return lockMatchesCurrentOwner(existing);
+}
+
+class MaintainerLifecycleAbort extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'MaintainerLifecycleAbort';
+  }
+}
+
+function createLifecycleProgress(lockFile) {
+  return () => {
+    if (shutdownRequested) {
+      throw new MaintainerLifecycleAbort('shutdown requested');
+    }
+    if (!stillOwnsLock(lockFile)) {
+      throw new MaintainerLifecycleAbort('lock ownership lost');
+    }
+    recordProgress(lockFile);
+  };
+}
+
+export async function runReconcileV2Tick(ctx) {
+  const onProgress = typeof ctx.onProgress === 'function' ? ctx.onProgress : null;
+  const progress = (phase) => { onProgress?.(phase); };
+  progress('tick:start');
+  // Baseline gate: the incremental reconciler must NEVER be the first index
+  // builder for a non-empty repo (product contract). Until the normal full
+  // indexing path has produced a complete baseline, stay dormant — skip BOTH
+  // the dirty-scan producer (so we don't enqueue the whole tree) AND the
+  // reconcile consumer (so we don't create partial codebase.db / code-graph.db
+  // / HNSW / LI / sparse artifacts that make search think the repo is indexed).
+  // No queue/artifact mutation here; the launcher still spawns the daemon, but
+  // each tick is a no-op until `sweet-search index` lands a baseline.
+  const baseline = hasCompleteBaseIndex(ctx.stateDir);
+  if (!baseline.ready) {
+    log('INFO', `${WAITING_FOR_INITIAL_INDEX}: no complete baseline yet (${baseline.reason}); run "sweet-search index" first — reconcile dormant`);
+    return { skipped: true, reason: WAITING_FOR_INITIAL_INDEX, baseline: baseline.reason };
+  }
+
+  // Producer step: diff the working tree against merkle-state.json and enqueue
+  // add/modify/delete hints, so ordinary edits are reconciled WITHOUT requiring
+  // `sweet-search index --add` or an editor hook (release-gate finding C1). Runs
+  // before the consume step below; best-effort so a scan failure never blocks
+  // reconcile of already-queued work.
+  try {
+    const { dirtyScanEnabled, scanDirtyAndEnqueue } = await import('../incremental-indexing/application/dirty-scan.mjs');
+    if (dirtyScanEnabled()) {
+      const { createAdmissionPolicy } = await import('../indexing/admission-policy.js');
+      const admissionPolicy = createAdmissionPolicy({ projectRoot: ctx.projectRoot });
+      progress('dirty-scan:start');
+      const scan = await scanDirtyAndEnqueue({ projectRoot: ctx.projectRoot, stateDir: ctx.stateDir, admissionPolicy, onProgress });
+      progress('dirty-scan:done');
+      if (scan.enqueued > 0) {
+        log('INFO', `Dirty scan enqueued ${scan.enqueued} file(s) (added=${scan.added}, modified=${scan.modified}, deleted=${scan.deleted}, retired=${scan.retired})`);
+      }
+    }
+  } catch (err) {
+    if (err instanceof MaintainerLifecycleAbort) throw err;
+    log('WARN', `Dirty scan failed (continuing with queued hints): ${err?.message ?? err}`);
+  }
+
+  const { runProductionReconcileTick } = await import('../incremental-indexing/application/production-reconciler.mjs');
+  const counters = await runProductionReconcileTick({
+    projectRoot: ctx.projectRoot,
+    stateDir: ctx.stateDir,
+    logger: {
+      info: (msg) => log('INFO', msg),
+      warn: (msg) => log('WARN', msg),
+      error: (msg) => log('ERROR', msg),
+    },
+    onProgress,
+  });
+  progress('tick:done');
+  log('INFO', `Reconcile v2 tick complete: epoch=${counters.epoch}, processed=${counters.files_processed}, unchanged=${counters.content_unchanged}`);
+  return counters;
+}
+
+/**
+ * Inline-drain decision for the reconcile daemon.
+ *
+ * Returns true unless the operator opts out via
+ * `SWEET_SEARCH_MAINTENANCE_INLINE=0|false|off`. The daemon owns the only
+ * `index-maintainer.lock` for this state dir, so a single inline drain
+ * inside the daemon process is the simplest "no two workers racing"
+ * topology — no child-process supervisor needed.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function maintenanceInlineEnabled(env = process.env) {
+  const raw = env.SWEET_SEARCH_MAINTENANCE_INLINE;
+  if (raw == null || raw === '') return true;
+  const normalized = String(raw).trim().toLowerCase();
+  return normalized !== '0' && normalized !== 'false' && normalized !== 'off';
+}
+
+/**
+ * Per-tick job cap for the inline drain. When the operator sets
+ * `SWEET_SEARCH_MAINTENANCE_MAX_JOBS_PER_TICK` it is honored as a hard
+ * ceiling; otherwise the drain is bounded by the wall-clock budget
+ * (`maintenanceInlineBudgetMs`) instead of a fixed tiny count, so it can
+ * keep pace with a growing backlog. Returns `undefined` (→ no job cap) in
+ * the unset case.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+function maintenanceInlineMaxJobs(env = process.env) {
+  const raw = Number.parseInt(env.SWEET_SEARCH_MAINTENANCE_MAX_JOBS_PER_TICK || '', 10);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  return undefined;
+}
+
+/**
+ * Wall-clock budget (ms) for one inline maintenance drain. Bounds how long
+ * the drain may run after a reconcile tick so it never starves reconcile,
+ * while still adapting to backlog. Tunable via
+ * `SWEET_SEARCH_MAINTENANCE_BUDGET_MS`.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+function maintenanceInlineBudgetMs(env = process.env) {
+  const raw = Number.parseInt(env.SWEET_SEARCH_MAINTENANCE_BUDGET_MS || '', 10);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  return 1500;
+}
+
+function maintenanceInlineMaxAttempts(env = process.env) {
+  const raw = Number.parseInt(env.SWEET_SEARCH_MAINTENANCE_MAX_ATTEMPTS || '', 10);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  return 3;
+}
+
+/**
+ * Grace window for the startup orphan-temp sweep. A staging temp older than
+ * this is a crash orphan (the rename that would publish it never happened);
+ * a younger one might belong to a concurrent in-flight writer and is left
+ * alone. Tunable via `SWEET_SEARCH_TMP_SWEEP_MAX_AGE_MS`; `0` disables the
+ * age gate (sweep everything that matches).
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+function tmpSweepMaxAgeMs(env = process.env) {
+  const raw = Number.parseInt(env.SWEET_SEARCH_TMP_SWEEP_MAX_AGE_MS || '', 10);
+  if (Number.isFinite(raw) && raw >= 0) return raw;
+  return DEFAULT_TMP_SWEEP_MAX_AGE_MS;
+}
+
+/**
+ * Bounded inline drain of the maintenance queue, intended to be called
+ * after a successful reconcile tick. Returns the drain summary, or
+ * `{skipped: true, reason}` when inline mode is disabled or the worker
+ * call throws (we never let maintenance failures crash the daemon).
+ *
+ * Exported so tests and the daemon main loop call the same code path.
+ *
+ * @param {{stateDir:string, env?:NodeJS.ProcessEnv}} ctx
+ */
+export async function drainMaintenanceInline(ctx) {
+  const onProgress = typeof ctx.onProgress === 'function' ? ctx.onProgress : null;
+  const env = ctx.env || process.env;
+  if (!maintenanceInlineEnabled(env)) {
+    return { skipped: true, reason: 'inline-disabled' };
+  }
+  let processMaintenanceQueue;
+  let defaultMaintenanceHandlers;
+  try {
+    ({ processMaintenanceQueue, defaultMaintenanceHandlers } = await import(
+      '../incremental-indexing/application/maintenance-worker.mjs'
+    ));
+  } catch (err) {
+    log('WARN', `Maintenance worker import failed: ${err?.message ?? err}`);
+    return { skipped: true, reason: 'import-failed' };
+  }
+  try {
+    const summary = await processMaintenanceQueue(ctx.stateDir, {
+      handlers: defaultMaintenanceHandlers(ctx.stateDir),
+      maxJobs: maintenanceInlineMaxJobs(env),
+      budgetMs: maintenanceInlineBudgetMs(env),
+      maxAttempts: maintenanceInlineMaxAttempts(env),
+      onProgress,
+    });
+    if (summary.seen > 0) {
+      log('INFO',
+        `Maintenance drain: seen=${summary.seen}, succeeded=${summary.succeeded}, ` +
+        `deferred=${summary.deferred}, retried=${summary.retried}, ` +
+        `deadLettered=${summary.deadLettered}, remaining=${summary.remaining}`);
+    }
+    return summary;
+  } catch (err) {
+    if (err instanceof MaintainerLifecycleAbort) throw err;
+    log('WARN', `Maintenance drain failed (continuing reconcile): ${err?.message ?? err}`);
+    return { skipped: true, reason: 'drain-error', error: err?.message ?? String(err) };
+  }
+}
+
+async function sleepWithProgress(totalMs, lockFile) {
+  const deadline = Date.now() + totalMs;
+  while (!shutdownRequested) {
+    if (!stillOwnsLock(lockFile)) {
+      throw new MaintainerLifecycleAbort('lock ownership lost during sleep');
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return;
+    await new Promise((resolveSleep) => setTimeout(resolveSleep, Math.min(LOCK_REFRESH_INTERVAL, remaining)));
+    if (!shutdownRequested) createLifecycleProgress(lockFile)();
+  }
+}
+
+async function runReconcileV2Main({ runOnce, merkleOnce }) {
+  const ctx = reconcileV2Context();
+  mkdirSync(ctx.stateDir, { recursive: true });
+  if (runOnce || merkleOnce) {
+    await runReconcileV2Tick(ctx);
+    await drainMaintenanceInline(ctx);
+    return;
+  }
+
+  const lock = await acquireStateLock(ctx.stateDir);
+  if (!lock.acquired) {
+    log('INFO', `Another reconcile v2 maintainer is running for ${ctx.stateDir}, exiting.`);
+    return;
+  }
+  log('INFO', `Reconcile v2 lock acquired (PID: ${process.pid})`);
+
+  // Crash-orphan sweep. We hold the exclusive state lock, so any staging
+  // temp left over (`*.tmp.<pid>`, `*.compacting.tmp`, `*.json.tmp`,
+  // `*.bin.tmp`, `*.selfheal.tmp`) is from a writer that died before its
+  // rename. Age-gated; never touches canonical artifacts, queues, WAL, or
+  // the lockfile (see artifact-temp-sweep.mjs). Best-effort: never let
+  // cleanup failure stop the daemon from starting.
+  try {
+    const sweep = sweepStaleArtifactTemps(ctx.stateDir, { maxAgeMs: tmpSweepMaxAgeMs() });
+    if (sweep.removed > 0) {
+      log('INFO', `Swept ${sweep.removed} orphaned staging temp(s) (${sweep.bytesReclaimed} bytes) from ${ctx.stateDir}`);
+    }
+  } catch (err) {
+    log('WARN', `Artifact temp sweep failed (continuing startup): ${err?.message ?? err}`);
+  }
+
+  const resolved = resolveReconcileV2Interval();
+  const intervalMs = resolved.intervalMs;
+  log('INFO', `Reconcile v2 interval ${intervalMs}ms (source=${resolved.source}${resolved.tier ? `, tier=${resolved.tier}` : ''})`);
+  // Lifecycle fix: only refresh the heartbeat if we still own the lock. If a
+  // wedged-backstop takeover stole it, the lockfile now names another pid —
+  // we must NOT clobber that successor with our pid. The main loop's
+  // ownership check will end this maintainer at the next iteration.
+  const refresh = setInterval(() => {
+    if (stillOwnsLock(lock.lockFile)) writeStateLock(lock.lockFile);
+  }, LOCK_REFRESH_INTERVAL);
+  const shutdown = () => { shutdownRequested = true; };
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+  process.on('exit', () => releaseStateLock(lock.lockFile));
+
+  try {
+    while (!shutdownRequested) {
+      // Lifecycle fix: bail out if the lock no longer names us. This is the
+      // backstop that ensures any displacement path (wedged-takeover,
+      // alive-but-stuck takeover, manual unlink) never leaves an immortal
+      // twin maintainer behind — the displaced daemon self-exits at the
+      // next loop iteration instead of looping forever as a PPID=1 orphan.
+      // Checked BEFORE the tick (not after) so a displaced daemon never
+      // starts new work while another maintainer owns the lock.
+      if (!stillOwnsLock(lock.lockFile)) {
+        log('WARN', `Lock no longer owned by pid=${process.pid}; another maintainer has taken over. Exiting cleanly.`);
+        shutdownRequested = true;
+        break;
+      }
+      // Lifecycle fix v2: progress checkpoint at the top of each iteration.
+      // Combined with the post-tick / post-drain checkpoints below this lets
+      // acquireStateLock distinguish a busy-but-progressing daemon from one
+      // hung on a never-resolving await — see the WEDGED_KILL_GRACE_MS block.
+      recordProgress(lock.lockFile);
+      const pause = isReconcilePaused(ctx.stateDir);
+      if (pause.paused) {
+        log('INFO', `Automatic reconcile v2 work paused${pause.pausedAt ? ` since ${pause.pausedAt}` : ''}`);
+      } else {
+        try {
+          const onProgress = createLifecycleProgress(lock.lockFile);
+          await runReconcileV2Tick({ ...ctx, onProgress });
+          onProgress('tick:post');  // post-tick checkpoint
+          await drainMaintenanceInline({ ...ctx, onProgress });
+          onProgress('drain:post');  // post-drain checkpoint
+        } catch (err) {
+          if (err instanceof MaintainerLifecycleAbort) {
+            log('WARN', `Reconcile v2 lifecycle abort: ${err.message}. Cleaning up cancellation-orphaned temps and exiting cleanly.`);
+            // Caveat-1 fix: on cancellation, immediately remove our own
+            // staging temps so they don't sit on disk waiting for the next
+            // daemon startup to sweep them. Safe to use maxAgeMs=0 here
+            // because (a) sweepStaleArtifactTemps uses a strict allowlist
+            // of staging-temp suffixes — it never touches canonical
+            // artifacts, queues, WAL, or the lockfile — and (b) maintenance
+            // handlers run sequentially via processMaintenanceQueue, so no
+            // concurrent writer is mid-rename when this fires.
+            try {
+              const sweep = sweepStaleArtifactTemps(ctx.stateDir, { maxAgeMs: 0 });
+              if (sweep.removed > 0) {
+                log('INFO', `Cancellation cleanup swept ${sweep.removed} orphaned staging temp(s) (${sweep.bytesReclaimed} bytes)`);
+              }
+            } catch (sweepErr) {
+              log('WARN', `Cancellation cleanup sweep failed (non-fatal): ${sweepErr?.message ?? sweepErr}`);
+            }
+            shutdownRequested = true;
+            break;
+          }
+          log('ERROR', `Reconcile v2 tick failed: ${err?.message ?? err}`);
+        }
+      }
+      await sleepWithProgress(intervalMs, lock.lockFile);
+    }
+  } finally {
+    clearInterval(refresh);
+    releaseStateLock(lock.lockFile);
+    log('INFO', 'Reconcile v2 shutdown complete');
+  }
+}
+
 /**
  * Normalize file path to project-relative format with cross-platform support.
  * Handles Windows paths (C:\Users\...), UNC paths (\\server\share), and converts
@@ -962,7 +1617,7 @@ function releaseGlobalIndexLock() {
 
 /**
  * Perform merkle-state check for ALL file changes (internal + external).
- * Uses mtime/size fast-path for efficiency (~0.1ms per unchanged file).
+ * Uses mtime/size/inode fast-path for efficiency (~0.1ms per unchanged file).
  *
  * @returns {Promise<{checked: boolean, toIndex: string[], toRemove: string[], stats: Object}>}
  */
@@ -972,7 +1627,7 @@ async function performMerkleCheck() {
 
   try {
     // Dynamically import incremental tracker
-    const { getChangedFiles, updateState } = await import('../../core/incremental-tracker.js');
+    const { getChangedFiles, updateState } = await import('./incremental-tracker.js');
 
     // H3 FIX: Use dynamic loader with fallback paths
     const fg = await loadFastGlob();
@@ -987,7 +1642,7 @@ async function performMerkleCheck() {
       return { checked: true, toIndex: [], toRemove: [], stats: { totalFiles: 0 } };
     }
 
-    // Use incremental tracker to detect changes (mtime/size fast-path)
+    // Use incremental tracker to detect changes (mtime/size/inode fast-path)
     const { toIndex, toRemove, currentHashes, fastPathStats } = await getChangedFiles(allFiles, PROJECT_ROOT);
 
     const duration = Date.now() - startTime;
@@ -1521,6 +2176,19 @@ async function main() {
 
   // L1 FIX: Updated version to v3
   log('INFO', 'Starting index maintainer daemon v3...');
+  const v2 = reconcileV2Status();
+  if (v2.enabled) {
+    if (v2.source === 'env-enabled') {
+      log('INFO', 'SWEET_SEARCH_RECONCILE_V2 enabled; using production Reconciler adapters');
+    } else if (v2.source === 'env-enabled-permissive') {
+      log('WARN', `SWEET_SEARCH_RECONCILE_V2="${v2.raw}" not recognized; treating as enabled (use 0/false/off to disable). Using production Reconciler adapters`);
+    } else {
+      log('INFO', 'Incremental reconcile v2 enabled by default (opt out with SWEET_SEARCH_RECONCILE_V2=0); using production Reconciler adapters');
+    }
+    await runReconcileV2Main({ runOnce, merkleOnce });
+    return;
+  }
+  log('INFO', 'Incremental reconcile v2 disabled via SWEET_SEARCH_RECONCILE_V2; using legacy queue/merkle path');
 
   // Ensure .sweet-search directory exists
   ensureDataDir();
@@ -1580,6 +2248,23 @@ async function main() {
     log('INFO', 'Lock released, goodbye.');
   });
 
+  let pauseLogged = false;
+  const automaticWorkPaused = () => {
+    const pause = isReconcilePaused();
+    if (pause.paused) {
+      if (!pauseLogged) {
+        log('INFO', `Automatic reconcile work paused${pause.pausedAt ? ` since ${pause.pausedAt}` : ''}`);
+        pauseLogged = true;
+      }
+      return true;
+    }
+    if (pauseLogged) {
+      log('INFO', 'Automatic reconcile work resumed');
+      pauseLogged = false;
+    }
+    return false;
+  };
+
   // Refresh lock periodically to prevent stale detection
   const lockRefreshInterval = setInterval(() => {
     if (!shutdownRequested) {
@@ -1600,6 +2285,7 @@ async function main() {
     try {
       if (shutdownRequested) return;
       startupTimeout = null;  // Clear reference after execution
+      if (automaticWorkPaused()) return;
       log('INFO', `Running deferred first merkle check (after ${STARTUP_DELAY}ms delay)...`);
       await runMerkleCheckAndIndex();
     } catch (err) {
@@ -1614,6 +2300,7 @@ async function main() {
   const merkleCheckInterval = setInterval(async () => {
     try {
       if (shutdownRequested) return;
+      if (automaticWorkPaused()) return;
       log('INFO', 'Running periodic merkle check...');
       await runMerkleCheckAndIndex();
     } catch (err) {
@@ -1626,6 +2313,11 @@ async function main() {
   let consecutiveEmptyPolls = 0;
 
   while (!shutdownRequested) {
+    if (automaticWorkPaused()) {
+      await new Promise(r => setTimeout(r, POLL_INTERVAL));
+      continue;
+    }
+
     // H5 FIX: Atomic queue check and process (prevents race between peek and acquire)
     const result = await atomicCheckAndProcessQueue({ dryRun });