@dench.com/cli 0.3.1 → 0.3.3

package/fs-daemon.ts

@@ -18,7 +18,22 @@
  *   • Optimistic conflict via `expectedPreviousHash`. On 409, we fetch
  *     latest, write to `<path>.conflicted-<ts>`, surface in UI.
  *   • Per-path circuit breaker: if a path syncs >5 times in 10s, pause
- *     sync on that path and emit a runEvents warning.
+ *     sync on that path and log loudly to stderr (the live state of
+ *     active breakers is exposed via `dench fs status`).
+ *
+ * FUSE / Mountpoint-for-S3 caveats:
+ *   /workspace is a Daytona persistent volume, mounted via AWS
+ *   Mountpoint for S3 (a FUSE driver). Two upstream limitations
+ *   matter:
+ *     • inotify events never fire on the mount
+ *       (awslabs/mountpoint-s3#1290). We auto-detect FUSE backing via
+ *       `/proc/self/mountinfo` and switch chokidar to `usePolling`
+ *       mode in that case.
+ *     • rename(2) returns ENOSYS on general-purpose buckets, so the
+ *       daemon never relies on rename to detect moves; we just see
+ *       add/unlink pairs through chokidar's polling backend.
+ *   A periodic reconciliation walk also runs on a 5s tick (10s on
+ *   non-FUSE) to catch anything chokidar missed.
  *
  * Live streaming subcommands (one-shot, not persistent):
  *   dench-fs-daemon stream-open <path>            -> prints token
@@ -35,10 +50,23 @@
  */
 import { createHash } from "node:crypto";
 import { mkdirSync } from "node:fs";
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import {
+  mkdir,
+  readdir,
+  readFile,
+  stat,
+  writeFile,
+} from "node:fs/promises";
 import { dirname, relative } from "node:path";
 import { ConvexClient, ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
+import {
+  detectWorkspaceFsType,
+  findMountForPath,
+  isFuseFsType,
+  type MountInfo,
+  readMountInfo,
+} from "./fs-daemon-mount";
 
 type Args = {
   orgId?: string;
@@ -79,6 +107,7 @@ function parseArgs(argv: string[]): Args {
 function shouldIgnore(relPath: string): boolean {
   const parts = relPath.split("/").filter(Boolean);
   const blockedDirs = new Set([
+    ".chrome-profile",
     ".git",
     ".next",
     ".vercel",
@@ -110,12 +139,29 @@ const SYNC_DEBOUNCE_MS = 300;
 const MAX_INLINE_TEXT_BYTES = 100_000;
 const CIRCUIT_BREAKER_LIMIT = 5;
 const CIRCUIT_BREAKER_WINDOW_MS = 10_000;
+const CIRCUIT_BREAKER_PAUSE_MS = 60_000;
+// Reconciliation interval. AWS documents Mountpoint-for-S3's metadata
+// staleness window at ~1s; polling tighter than 2s wastes round-trips
+// without catching anything new.
+const RECONCILE_INTERVAL_FUSE_MS = 5_000;
+const RECONCILE_INTERVAL_DEFAULT_MS = 30_000;
+// Status / breaker state visible to `dench fs status` over a tiny
+// JSON file the daemon refreshes after each tick.
+const DAEMON_STATUS_PATH = "/tmp/dench-fs-daemon.status.json";
+
+type BreakerState = {
+  path: string;
+  trippedAt: number;
+  resumesAt: number;
+  syncsInWindow: number;
+};
 
 class HashTracker {
   private hashes = new Map<string, string>();
   private timers = new Map<string, NodeJS.Timeout>();
   private recentSyncs = new Map<string, number[]>();
-  private paused = new Set<string>();
+  private paused = new Map<string, BreakerState>();
+  private onBreakerTrip?: (state: BreakerState) => void;
 
   get(absPath: string): string | undefined {
     return this.hashes.get(absPath);
@@ -125,6 +171,29 @@ class HashTracker {
     this.hashes.set(absPath, hash);
   }
 
+  forget(absPath: string): void {
+    this.hashes.delete(absPath);
+    const timer = this.timers.get(absPath);
+    if (timer) {
+      clearTimeout(timer);
+      this.timers.delete(absPath);
+    }
+    this.recentSyncs.delete(absPath);
+    this.paused.delete(absPath);
+  }
+
+  knownPaths(): string[] {
+    return [...this.hashes.keys()];
+  }
+
+  activeBreakers(): BreakerState[] {
+    return [...this.paused.values()];
+  }
+
+  setBreakerListener(listener: (state: BreakerState) => void): void {
+    this.onBreakerTrip = listener;
+  }
+
   /**
    * Returns true if the path is currently throttled by the circuit
    * breaker (>5 syncs in the last 10s).
@@ -138,17 +207,26 @@ class HashTracker {
     recent.push(now);
     this.recentSyncs.set(absPath, recent);
     if (recent.length > CIRCUIT_BREAKER_LIMIT) {
-      this.paused.add(absPath);
-      console.warn(
-        `[dench-fs-daemon] circuit breaker tripped for ${absPath}; pausing sync for 60s`,
+      const state: BreakerState = {
+        path: absPath,
+        trippedAt: now,
+        resumesAt: now + CIRCUIT_BREAKER_PAUSE_MS,
+        syncsInWindow: recent.length,
+      };
+      this.paused.set(absPath, state);
+      // Loud enough to land in the supervisor's tail of fs-daemon.log
+      // (sandbox-bootstrap.ts surfaces the last 50 lines on failure).
+      console.error(
+        `[dench-fs-daemon] CIRCUIT_BREAKER tripped path=${absPath} syncs=${recent.length} pause=${CIRCUIT_BREAKER_PAUSE_MS}ms`,
       );
+      this.onBreakerTrip?.(state);
       setTimeout(() => {
         this.paused.delete(absPath);
         this.recentSyncs.delete(absPath);
         console.warn(
           `[dench-fs-daemon] circuit breaker released for ${absPath}`,
         );
-      }, 60_000);
+      }, CIRCUIT_BREAKER_PAUSE_MS);
       return true;
     }
     return false;
@@ -171,6 +249,18 @@ class HashTracker {
   }
 }
 
+// Mount detection helpers live in fs-daemon-mount.ts so they can be
+// unit-tested without pulling chokidar / convex / etc. They are
+// re-exported here so existing imports of `cli/fs-daemon` keep
+// working in case anything outside this file relied on them.
+export {
+  detectWorkspaceFsType,
+  findMountForPath,
+  isFuseFsType,
+  readMountInfo,
+  type MountInfo,
+};
+
 // Convex function references — must match `convex/_generated/api.d.ts` paths.
 const api = {
   files: {
@@ -276,6 +366,21 @@ class DenchFileClient {
     });
   }
 
+  /**
+   * Read direct children of a Convex file-tree prefix. Used by `dench
+   * fs status` to recursively crawl the canonical tree and diff
+   * against the local FS snapshot.
+   */
+  async listTree(prefix: string): Promise<
+    Array<{ path: string; contentHash?: string; isDir: boolean }>
+  > {
+    const rows = (await this.http.query(api.files.listTree, {
+      prefix,
+      apiKey: this.apiKey,
+    })) as Array<{ path: string; contentHash?: string; isDir: boolean }>;
+    return Array.isArray(rows) ? rows : [];
+  }
+
   async getSignedDownloadUrl(path: string): Promise<string | null> {
     const url = (await this.http.action(api.files.getFileSignedDownloadUrl, {
       path,
@@ -359,45 +464,80 @@ async function pullDownRemoteFile(
   );
 }
 
+/**
+ * sysexits.h-style exit codes the supervisor (in
+ * src/lib/daytona/sandbox-bootstrap.ts) recognizes as **permanent** —
+ * keep restarting won't fix a missing env var or a missing dependency,
+ * so the supervisor gives up instead of crash-looping. Anything else
+ * (network blip, transient Convex error) exits 1 and gets retried.
+ */
+const EXIT_CONFIG_ERROR = 78;
+
 async function runDaemon(daemonArgs: Args): Promise<void> {
   const convexUrl = process.env.CONVEX_URL?.trim();
   const apiKey = process.env.DENCH_API_KEY?.trim();
   if (!convexUrl || !apiKey) {
     console.error(
-      "[dench-fs-daemon] CONVEX_URL or DENCH_API_KEY missing in env; nothing to sync",
+      "[dench-fs-daemon] CONVEX_URL or DENCH_API_KEY missing in env; refusing to start",
     );
-    setInterval(() => undefined, 60_000);
-    return;
+    process.exit(EXIT_CONFIG_ERROR);
   }
 
   const client = new DenchFileClient(convexUrl, apiKey);
   const resolvedOrgId =
     daemonArgs.orgId ?? (await client.resolveOrganizationId());
+  const mount = await detectWorkspaceFsType(daemonArgs.workspace);
   console.log(
-    `[dench-fs-daemon] starting org=${resolvedOrgId} workspace=${daemonArgs.workspace}`,
+    `[dench-fs-daemon] starting org=${resolvedOrgId} workspace=${daemonArgs.workspace} fsType=${mount.fsType}${mount.isFuse ? " (FUSE)" : ""}`,
   );
+  if (mount.isFuse) {
+    console.log(
+      "[dench-fs-daemon] FUSE backing detected; enabling polling mode (inotify is not delivered through Mountpoint-S3)",
+    );
+  }
   mkdirSync(daemonArgs.workspace, { recursive: true });
   mkdirSync(daemonArgs.hotCache, { recursive: true });
 
   const tracker = new HashTracker();
+  const status = new DaemonStatusWriter({
+    workspace: daemonArgs.workspace,
+    organizationId: resolvedOrgId,
+    fsType: mount.fsType,
+    isFuse: mount.isFuse,
+  });
+  tracker.setBreakerListener((breakerState) => {
+    status.recordBreakerEvent(breakerState);
+    void status.flush();
+  });
+  await status.flush();
 
   let chokidar: typeof import("chokidar");
   try {
     chokidar = (await import("chokidar")) as never;
   } catch (error) {
     console.error(
-      `[dench-fs-daemon] chokidar not available; running in idle mode (${
+      `[dench-fs-daemon] chokidar not available; refusing to start (${
         error instanceof Error ? error.message : String(error)
       })`,
     );
-    setInterval(() => undefined, 60_000);
-    return;
+    process.exit(EXIT_CONFIG_ERROR);
   }
 
+  // On FUSE mounts inotify never fires, so we force chokidar's polling
+  // backend (poll every 2.5s for files / 5s for binary). On non-FUSE
+  // mounts the inotify backend is fine and saves CPU.
+  const reconcileIntervalMs = mount.isFuse
+    ? RECONCILE_INTERVAL_FUSE_MS
+    : RECONCILE_INTERVAL_DEFAULT_MS;
   const watcher = chokidar.watch(daemonArgs.workspace, {
     ignoreInitial: true,
     persistent: true,
-    awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+    usePolling: mount.isFuse,
+    interval: mount.isFuse ? 2_500 : undefined,
+    binaryInterval: mount.isFuse ? 5_000 : undefined,
+    awaitWriteFinish: mount.isFuse
+      ? false
+      : { stabilityThreshold: 100, pollInterval: 50 },
     ignored: (path: string) => {
       const rel = relative(daemonArgs.workspace, path);
       if (rel.startsWith("..")) return true;
@@ -412,6 +552,7 @@ async function runDaemon(daemonArgs: Args): Promise<void> {
     if (shouldIgnore(rel)) return;
     try {
       await client.deleteFile(`/${rel}`);
+      tracker.forget(absPath);
       console.log(`[dench-fs-daemon] deleted /${rel}`);
     } catch (error) {
       console.error(
@@ -500,16 +641,271 @@ async function runDaemon(daemonArgs: Args): Promise<void> {
     }
   });
 
+  // Periodic walk + reconciliation. Catches changes chokidar missed
+  // (any file write on a Mountpoint volume from a process other than
+  // this sandbox, or from the Daytona SDK uploadFile path) and writes
+  // a heartbeat to the status file so `dench fs status` can confirm
+  // the daemon is alive and what it last did.
+  const stopReconcile = startReconcileLoop({
+    workspace: daemonArgs.workspace,
+    intervalMs: reconcileIntervalMs,
+    tracker,
+    status,
+    onLocalChange: scheduleSync,
+    onLocalDelete: async (absPath) => {
+      const rel = relative(daemonArgs.workspace, absPath);
+      if (shouldIgnore(rel)) return;
+      try {
+        await client.deleteFile(`/${rel}`);
+        tracker.forget(absPath);
+        console.log(
+          `[dench-fs-daemon] reconcile deleted /${rel} (chokidar missed unlink)`,
+        );
+      } catch (error) {
+        console.error(
+          `[dench-fs-daemon] reconcile delete failed for /${rel}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    },
+  });
+
   process.on("SIGTERM", () => {
+    stopReconcile();
     unsubscribe();
     watcher.close().catch(() => undefined);
     process.exit(0);
   });
 
-  console.log(`[dench-fs-daemon] watching ${daemonArgs.workspace}`);
+  console.log(
+    `[dench-fs-daemon] watching ${daemonArgs.workspace} (reconcile every ${reconcileIntervalMs}ms)`,
+  );
   setInterval(() => undefined, 60_000);
 }
 
+// ── Reconciliation loop ────────────────────────────────────────────────────
+//
+// Runs on a fixed tick and:
+//   • Walks the workspace, collects (absPath, mtimeMs, size) for every
+//     non-ignored file.
+//   • Compares against the in-memory tracker (`tracker.knownPaths()`).
+//     New paths or paths whose mtime/size moved → schedule a sync.
+//   • Paths the tracker knew about that are now absent from disk →
+//     enqueue a delete.
+//   • Refreshes the daemon status file with the latest scan summary.
+
+type FileSnapshot = {
+  absPath: string;
+  size: number;
+  mtimeMs: number;
+};
+
+async function snapshotWorkspace(
+  workspace: string,
+): Promise<Map<string, FileSnapshot>> {
+  const result = new Map<string, FileSnapshot>();
+  const queue: string[] = [workspace];
+  while (queue.length > 0) {
+    const dir = queue.shift()!;
+    type DirEntryLike = {
+      name: string;
+      isDirectory(): boolean;
+      isFile(): boolean;
+    };
+    let entries: DirEntryLike[];
+    try {
+      entries = (await readdir(dir, {
+        withFileTypes: true,
+      })) as unknown as DirEntryLike[];
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const abs = `${dir.replace(/\/+$/, "")}/${entry.name}`;
+      const rel = relative(workspace, abs);
+      if (rel.startsWith("..") || shouldIgnore(rel)) continue;
+      if (entry.isDirectory()) {
+        queue.push(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      const stats = await stat(abs).catch(() => null);
+      if (!stats) continue;
+      result.set(abs, {
+        absPath: abs,
+        size: stats.size,
+        mtimeMs: stats.mtimeMs,
+      });
+    }
+  }
+  return result;
+}
+
+function startReconcileLoop(args: {
+  workspace: string;
+  intervalMs: number;
+  tracker: HashTracker;
+  status: DaemonStatusWriter;
+  onLocalChange: (absPath: string) => void;
+  onLocalDelete: (absPath: string) => Promise<void> | void;
+}): () => void {
+  const last = new Map<string, FileSnapshot>();
+
+  let stopped = false;
+  const tick = async () => {
+    if (stopped) return;
+    const start = Date.now();
+    let observed = 0;
+    let scheduled = 0;
+    let deleted = 0;
+    try {
+      const snapshot = await snapshotWorkspace(args.workspace);
+      observed = snapshot.size;
+      for (const [absPath, info] of snapshot) {
+        const prev = last.get(absPath);
+        if (!prev || prev.size !== info.size || prev.mtimeMs !== info.mtimeMs) {
+          args.onLocalChange(absPath);
+          scheduled++;
+        }
+      }
+      for (const absPath of last.keys()) {
+        if (!snapshot.has(absPath)) {
+          await args.onLocalDelete(absPath);
+          deleted++;
+        }
+      }
+      last.clear();
+      for (const [absPath, info] of snapshot) {
+        last.set(absPath, info);
+      }
+    } catch (error) {
+      console.error(
+        `[dench-fs-daemon] reconcile scan failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    } finally {
+      args.status.recordReconcile({
+        finishedAt: Date.now(),
+        durationMs: Date.now() - start,
+        observed,
+        scheduledForSync: scheduled,
+        deleted,
+        breakers: args.tracker.activeBreakers(),
+      });
+      await args.status.flush();
+    }
+  };
+
+  // Stagger the first tick so we don't race chokidar's initial add
+  // floods on daemon startup.
+  const initial = setTimeout(() => {
+    void tick();
+  }, Math.min(args.intervalMs, 5_000));
+  const interval = setInterval(() => {
+    void tick();
+  }, args.intervalMs);
+
+  return () => {
+    stopped = true;
+    clearTimeout(initial);
+    clearInterval(interval);
+  };
+}
+
+// ── Status file ────────────────────────────────────────────────────────────
+//
+// `dench fs status` reads /tmp/dench-fs-daemon.status.json so the agent
+// (and humans) can quickly see whether the daemon is alive, what
+// filesystem it thinks /workspace is on, and how many files it just
+// scanned. Lives on tmpfs so it never lands in the volume itself.
+
+type DaemonStatus = {
+  pid: number;
+  startedAt: number;
+  lastUpdatedAt: number;
+  workspace: string;
+  organizationId: string;
+  fsType: string;
+  isFuse: boolean;
+  lastReconcile: {
+    finishedAt: number;
+    durationMs: number;
+    observed: number;
+    scheduledForSync: number;
+    deleted: number;
+  } | null;
+  activeBreakers: BreakerState[];
+  recentBreakerEvents: BreakerState[];
+};
+
+class DaemonStatusWriter {
+  private state: DaemonStatus;
+  private writing: Promise<void> | null = null;
+
+  constructor(args: {
+    workspace: string;
+    organizationId: string;
+    fsType: string;
+    isFuse: boolean;
+  }) {
+    const now = Date.now();
+    this.state = {
+      pid: process.pid,
+      startedAt: now,
+      lastUpdatedAt: now,
+      workspace: args.workspace,
+      organizationId: args.organizationId,
+      fsType: args.fsType,
+      isFuse: args.isFuse,
+      lastReconcile: null,
+      activeBreakers: [],
+      recentBreakerEvents: [],
+    };
+  }
+
+  recordReconcile(args: {
+    finishedAt: number;
+    durationMs: number;
+    observed: number;
+    scheduledForSync: number;
+    deleted: number;
+    breakers: BreakerState[];
+  }): void {
+    this.state.lastReconcile = {
+      finishedAt: args.finishedAt,
+      durationMs: args.durationMs,
+      observed: args.observed,
+      scheduledForSync: args.scheduledForSync,
+      deleted: args.deleted,
+    };
+    this.state.activeBreakers = args.breakers;
+  }
+
+  recordBreakerEvent(state: BreakerState): void {
+    const recent = [...this.state.recentBreakerEvents, state];
+    // Cap at last 10 events so the file stays small.
+    while (recent.length > 10) recent.shift();
+    this.state.recentBreakerEvents = recent;
+  }
+
+  async flush(): Promise<void> {
+    this.state.lastUpdatedAt = Date.now();
+    const body = `${JSON.stringify(this.state, null, 2)}\n`;
+    // Serialize so concurrent flushes don't interleave writes.
+    const previous = this.writing ?? Promise.resolve();
+    this.writing = previous
+      .catch(() => undefined)
+      .then(() =>
+        writeFile(DAEMON_STATUS_PATH, body, { encoding: "utf-8" }).catch(
+          () => undefined,
+        ),
+      );
+    await this.writing;
+  }
+}
+
 // ── Live streaming subcommands ─────────────────────────────────────────────
 //
 // Tokens are stored in /tmp/dench-stream-tokens.json so subsequent stream-
@@ -616,10 +1012,366 @@ async function main(): Promise<void> {
     await runInitialSync(argv.slice(1));
     return;
   }
+  if (subcommand === "status") {
+    await runStatus(argv.slice(1));
+    return;
+  }
   // Daemon mode (long-running, started by sandbox-bootstrap).
   await runDaemon(parseArgs(argv));
 }
 
+// ── Status subcommand ─────────────────────────────────────────────────────
+//
+// `dench-fs-daemon status [--json] [--workspace /workspace]` prints a
+// quick health readout: process up?, last reconcile tick, active
+// circuit breakers, file count on disk vs Convex tree, and a
+// per-path drift list. Designed to be called from a sandbox shell
+// (or `dench fs status`) without any existing CLI context.
+
+const FS_DAEMON_LOG_PATH = "/var/log/dench/fs-daemon.log";
+
+type DriftItem =
+  | { kind: "only_disk"; path: string; size: number; mtimeMs: number }
+  | { kind: "only_convex"; path: string }
+  | {
+      kind: "hash_mismatch";
+      path: string;
+      diskSize: number;
+      diskHashShort: string;
+      convexHashShort: string;
+    };
+
+type StatusReport = {
+  daemon: {
+    pidAlive: boolean;
+    statusFilePath: string;
+    statusFileExists: boolean;
+    statusFileAgeMs: number | null;
+    state: DaemonStatus | null;
+  };
+  filesystem: {
+    workspace: string;
+    fsType: string;
+    isFuse: boolean;
+    source: string;
+  };
+  counts: {
+    onDisk: number;
+    inConvex: number;
+    onlyOnDisk: number;
+    onlyInConvex: number;
+    hashMismatches: number;
+  };
+  drift: DriftItem[];
+  recentLogTail: string[];
+};
+
+async function runStatus(argv: string[]): Promise<void> {
+  const json = argv.includes("--json");
+  const workspaceIndex = argv.indexOf("--workspace");
+  const workspace =
+    workspaceIndex === -1
+      ? (process.env.DENCH_VOLUME_PATH?.trim() || "/workspace")
+      : (argv[workspaceIndex + 1] ?? "/workspace");
+  const driftLimitIndex = argv.indexOf("--drift-limit");
+  const driftLimit =
+    driftLimitIndex === -1
+      ? 50
+      : Math.max(0, Number.parseInt(argv[driftLimitIndex + 1] ?? "50", 10));
+  const skipHash = argv.includes("--no-hash");
+
+  const report = await collectStatus({ workspace, driftLimit, hash: !skipHash });
+  if (json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+  printStatusHuman(report);
+  // Exit non-zero when the daemon is missing or has obvious drift —
+  // makes it usable in `if dench-fs-daemon status; then …` checks.
+  if (!report.daemon.pidAlive || report.counts.hashMismatches > 0) {
+    process.exitCode = 1;
+  }
+}
+
+async function collectStatus(args: {
+  workspace: string;
+  driftLimit: number;
+  hash: boolean;
+}): Promise<StatusReport> {
+  const [statusFile, mount, logTail] = await Promise.all([
+    readStatusFile(),
+    detectWorkspaceFsType(args.workspace),
+    readLogTail(20),
+  ]);
+
+  const pidAlive = statusFile.state ? isPidAlive(statusFile.state.pid) : false;
+
+  let onDiskList: Array<{ path: string; size: number; mtimeMs: number }> = [];
+  let convexRows: Array<{ path: string; contentHash?: string; isDir: boolean }> =
+    [];
+  try {
+    const snapshot = await snapshotWorkspace(args.workspace);
+    for (const [absPath, info] of snapshot) {
+      const rel = relative(args.workspace, absPath);
+      if (rel.startsWith("..")) continue;
+      onDiskList.push({
+        path: `/${rel}`,
+        size: info.size,
+        mtimeMs: info.mtimeMs,
+      });
+    }
+  } catch (error) {
+    console.error(
+      `[dench-fs-daemon] status: could not walk ${args.workspace}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  const convexUrl = process.env.CONVEX_URL?.trim();
+  const apiKey = process.env.DENCH_API_KEY?.trim();
+  if (convexUrl && apiKey) {
+    try {
+      const client = new DenchFileClient(convexUrl, apiKey);
+      convexRows = await collectConvexTree(client);
+    } catch (error) {
+      console.error(
+        `[dench-fs-daemon] status: convex query failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+
+  const diskByPath = new Map(onDiskList.map((item) => [item.path, item]));
+  const convexFileRows = convexRows.filter((row) => !row.isDir);
+  const convexByPath = new Map(convexFileRows.map((row) => [row.path, row]));
+
+  const drift: DriftItem[] = [];
+  let onlyDisk = 0;
+  let onlyConvex = 0;
+  let hashMismatches = 0;
+
+  for (const item of onDiskList) {
+    const convex = convexByPath.get(item.path);
+    if (!convex) {
+      onlyDisk++;
+      if (drift.length < args.driftLimit) {
+        drift.push({
+          kind: "only_disk",
+          path: item.path,
+          size: item.size,
+          mtimeMs: item.mtimeMs,
+        });
+      }
+      continue;
+    }
+    if (!args.hash) continue;
+    if (!convex.contentHash) continue;
+    try {
+      const bytes = await readFile(`${args.workspace}${item.path}`);
+      const diskHash = sha256(bytes);
+      if (diskHash !== convex.contentHash) {
+        hashMismatches++;
+        if (drift.length < args.driftLimit) {
+          drift.push({
+            kind: "hash_mismatch",
+            path: item.path,
+            diskSize: item.size,
+            diskHashShort: diskHash.slice(0, 8),
+            convexHashShort: convex.contentHash.slice(0, 8),
+          });
+        }
+      }
+    } catch {
+      // ignore read failures for a single file
+    }
+  }
+
+  for (const row of convexFileRows) {
+    if (!diskByPath.has(row.path)) {
+      onlyConvex++;
+      if (drift.length < args.driftLimit) {
+        drift.push({ kind: "only_convex", path: row.path });
+      }
+    }
+  }
+
+  let statusFileAgeMs: number | null = null;
+  if (statusFile.exists && statusFile.state) {
+    statusFileAgeMs = Date.now() - statusFile.state.lastUpdatedAt;
+  }
+
+  return {
+    daemon: {
+      pidAlive,
+      statusFilePath: DAEMON_STATUS_PATH,
+      statusFileExists: statusFile.exists,
+      statusFileAgeMs,
+      state: statusFile.state,
+    },
+    filesystem: {
+      workspace: args.workspace,
+      fsType: mount.fsType,
+      isFuse: mount.isFuse,
+      source: mount.source,
+    },
+    counts: {
+      onDisk: onDiskList.length,
+      inConvex: convexFileRows.length,
+      onlyOnDisk: onlyDisk,
+      onlyInConvex: onlyConvex,
+      hashMismatches,
+    },
+    drift,
+    recentLogTail: logTail,
+  };
+}
+
+async function readStatusFile(): Promise<{
+  exists: boolean;
+  state: DaemonStatus | null;
+}> {
+  try {
+    const text = await readFile(DAEMON_STATUS_PATH, "utf-8");
+    return { exists: true, state: JSON.parse(text) as DaemonStatus };
+  } catch {
+    return { exists: false, state: null };
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readLogTail(lines: number): Promise<string[]> {
+  try {
+    const text = await readFile(FS_DAEMON_LOG_PATH, "utf-8");
+    const all = text.split("\n").filter((line) => line.length > 0);
+    return all.slice(-lines);
+  } catch {
+    return [];
+  }
+}
+
+async function collectConvexTree(client: DenchFileClient): Promise<
+  Array<{ path: string; contentHash?: string; isDir: boolean }>
+> {
+  // listTree returns one directory's children; recurse into subdirs.
+  const out: Array<{ path: string; contentHash?: string; isDir: boolean }> =
+    [];
+  const queue: string[] = ["/"];
+  const seen = new Set<string>();
+  while (queue.length > 0) {
+    const prefix = queue.shift()!;
+    if (seen.has(prefix)) continue;
+    seen.add(prefix);
+    const rows = await client.listTree(prefix);
+    for (const row of rows) {
+      out.push({
+        path: row.path,
+        contentHash: row.contentHash,
+        isDir: row.isDir,
+      });
+      if (row.isDir) queue.push(row.path);
+    }
+  }
+  return out;
+}
+
+function printStatusHuman(report: StatusReport): void {
+  const lines: string[] = [];
+  lines.push("dench-fs-daemon status");
+  lines.push("─".repeat(40));
+  if (report.daemon.state) {
+    const ageSec =
+      report.daemon.statusFileAgeMs !== null
+        ? Math.round(report.daemon.statusFileAgeMs / 1000)
+        : null;
+    lines.push(
+      `daemon:          ${report.daemon.pidAlive ? "ALIVE" : "DEAD"} (pid ${report.daemon.state.pid})`,
+    );
+    lines.push(
+      `status file:     ${ageSec !== null ? `${ageSec}s old` : "missing"}`,
+    );
+    lines.push(`workspace:       ${report.filesystem.workspace}`);
+    lines.push(
+      `filesystem:      ${report.filesystem.fsType}${report.filesystem.isFuse ? " (FUSE — polling mode)" : ""}`,
+    );
+    if (report.daemon.state.lastReconcile) {
+      const r = report.daemon.state.lastReconcile;
+      const reconcileAge = Math.round((Date.now() - r.finishedAt) / 1000);
+      lines.push(
+        `last reconcile:  ${reconcileAge}s ago — observed=${r.observed} synced=${r.scheduledForSync} deleted=${r.deleted} (${r.durationMs}ms)`,
+      );
+    } else {
+      lines.push("last reconcile:  never");
+    }
+    if (report.daemon.state.activeBreakers.length > 0) {
+      lines.push(
+        `active breakers: ${report.daemon.state.activeBreakers.length}`,
+      );
+      for (const breaker of report.daemon.state.activeBreakers) {
+        const remain = Math.max(
+          0,
+          Math.round((breaker.resumesAt - Date.now()) / 1000),
+        );
+        lines.push(`  • ${breaker.path} (resumes in ${remain}s)`);
+      }
+    } else {
+      lines.push("active breakers: none");
+    }
+  } else {
+    lines.push(
+      `daemon:          NOT RUNNING (status file missing at ${report.daemon.statusFilePath})`,
+    );
+    lines.push(`workspace:       ${report.filesystem.workspace}`);
+    lines.push(
+      `filesystem:      ${report.filesystem.fsType}${report.filesystem.isFuse ? " (FUSE — would use polling)" : ""}`,
+    );
+  }
+  lines.push("");
+  lines.push("file counts");
+  lines.push("─".repeat(40));
+  lines.push(`on disk:         ${report.counts.onDisk}`);
+  lines.push(`in convex:       ${report.counts.inConvex}`);
+  lines.push(`only on disk:    ${report.counts.onlyOnDisk}`);
+  lines.push(`only in convex:  ${report.counts.onlyInConvex}`);
+  lines.push(`hash mismatches: ${report.counts.hashMismatches}`);
+
+  if (report.drift.length > 0) {
+    lines.push("");
+    lines.push(`drift (first ${report.drift.length})`);
+    lines.push("─".repeat(40));
+    for (const item of report.drift) {
+      if (item.kind === "only_disk") {
+        lines.push(`  + ${item.path}  ${item.size}B (only on disk)`);
+      } else if (item.kind === "only_convex") {
+        lines.push(`  - ${item.path}  (only in convex)`);
+      } else {
+        lines.push(
+          `  ! ${item.path}  disk=${item.diskHashShort}… convex=${item.convexHashShort}…`,
+        );
+      }
+    }
+  }
+
+  if (report.recentLogTail.length > 0) {
+    lines.push("");
+    lines.push("recent log tail");
+    lines.push("─".repeat(40));
+    for (const line of report.recentLogTail) lines.push(line);
+  }
+
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
 /**
  * One-shot recursive sync. Walks the workspace + uploads every file to
  * Convex Storage / commitFileUpload. Used by the migration script
@@ -699,16 +1451,38 @@ async function runInitialSync(argv: string[]): Promise<void> {
   );
 }
 
-main().catch((error) => {
-  console.error(
-    `[dench-fs-daemon] fatal: ${
-      error instanceof Error ? (error.stack ?? error.message) : String(error)
-    }`,
-  );
-  // Long-running daemon: don't exit on transient errors. One-shot
-  // subcommands use a non-zero exit so callers see failure.
-  if (process.argv.slice(2)[0]?.startsWith("stream-")) {
-    process.exit(1);
+/**
+ * Only auto-run when this file is the entry point. Tests import named
+ * exports (`readMountInfo`, `findMountForPath`, `isFuseFsType`,
+ * etc.) and must not trigger the daemon's main loop. The check below
+ * tolerates Bun (`process.argv[1]`), the npm-installed wrapper
+ * (`require.main === module`), and the dench CLI's `tsx`-based
+ * fallback (`import.meta.main`).
+ */
+const isDirectEntrypoint = (() => {
+  try {
+    if (typeof require !== "undefined" && require.main === module) return true;
+  } catch {
+    // require / module aren't defined in pure ESM mode; fall through.
   }
-  setInterval(() => undefined, 60_000);
-});
+  // biome-ignore lint/suspicious/noExplicitAny: Bun-specific import.meta property
+  if ((import.meta as any).main === true) return true;
+  const entry = process.argv[1] ?? "";
+  return entry.endsWith("fs-daemon.ts") || entry.endsWith("/fs-daemon");
+})();
+
+if (isDirectEntrypoint) {
+  main().catch((error) => {
+    console.error(
+      `[dench-fs-daemon] fatal: ${
+        error instanceof Error ? (error.stack ?? error.message) : String(error)
+      }`,
+    );
+    // Always exit with a non-zero code so the supervisor (in
+    // src/lib/daytona/sandbox-bootstrap.ts) can decide whether to
+    // restart. Previously we parked the process on a noop interval,
+    // which made `pgrep dench-fs-daemon` report "alive" for a daemon
+    // that had silently given up syncing.
+    process.exit(1);
+  });
+}