@dench.com/cli 0.4.0 → 0.4.2

package/fs-daemon.ts

@@ -50,16 +50,16 @@
  */
 import { createHash } from "node:crypto";
 import { mkdirSync } from "node:fs";
-import {
-  mkdir,
-  readdir,
-  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 { decodeInlineTextOrUndefined } from "./fs-daemon-binary";
+import {
+  type DrainStatus,
+  FLUSH_DEFAULT_TIMEOUT_MS,
+  runFlushPolling,
+} from "./fs-daemon-flush";
 import {
   detectWorkspaceFsType,
   findMountForPath,
@@ -156,12 +156,20 @@ type BreakerState = {
   syncsInWindow: number;
 };
 
+// `DrainStatus` lives in cli/fs-daemon-flush.ts so the flush subcommand's
+// polling helper can import it without dragging in the daemon's main
+// entrypoint (which would crash test runners that import this file).
+
 class HashTracker {
   private hashes = new Map<string, string>();
   private timers = new Map<string, NodeJS.Timeout>();
   private recentSyncs = new Map<string, number[]>();
   private paused = new Map<string, BreakerState>();
   private onBreakerTrip?: (state: BreakerState) => void;
+  // Bumped right before each scheduled fn() actually starts; decremented
+  // in the fn()'s `.finally()`. The flush subcommand reads this through
+  // `drainStatus()` (mirrored into the status file once per reconcile).
+  private inFlightUploads = 0;
 
   get(absPath: string): string | undefined {
     return this.hashes.get(absPath);
@@ -237,16 +245,37 @@ class HashTracker {
     if (existing) clearTimeout(existing);
     const timer = setTimeout(() => {
       this.timers.delete(absPath);
-      fn().catch((error) => {
-        console.error(
-          `[dench-fs-daemon] sync failed for ${absPath}: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-      });
+      // Track this work in-flight so `flush` knows to wait for the
+      // upload to actually finish, not just for the next reconcile
+      // tick to fire. The decrement runs in `finally` so even a
+      // throwing upload doesn't strand the counter at non-zero.
+      this.inFlightUploads += 1;
+      fn()
+        .catch((error) => {
+          console.error(
+            `[dench-fs-daemon] sync failed for ${absPath}: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+        })
+        .finally(() => {
+          this.inFlightUploads = Math.max(0, this.inFlightUploads - 1);
+        });
     }, ms);
     this.timers.set(absPath, timer);
   }
+
+  /**
+   * Snapshot of pending sync work. Mirrored into the daemon status
+   * file once per reconcile tick so `dench-fs-daemon flush` can wait
+   * on it without an IPC channel.
+   */
+  drainStatus(): DrainStatus {
+    return {
+      pendingPaths: this.timers.size,
+      inFlightUploads: this.inFlightUploads,
+    };
+  }
 }
 
 // Mount detection helpers live in fs-daemon-mount.ts so they can be
@@ -284,6 +313,9 @@ const api = {
     getFileSignedDownloadUrl: makeFunctionReference<"action">(
       "functions/files:getFileSignedDownloadUrl",
     ),
+    reportDaemonHealth: makeFunctionReference<"mutation">(
+      "functions/files:reportDaemonHealth",
+    ),
   },
 };
 
@@ -371,9 +403,9 @@ class DenchFileClient {
    * 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 }>
-  > {
+  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,
@@ -407,6 +439,27 @@ class DenchFileClient {
     });
   }
 
+  /**
+   * Heartbeat the per-org `fileTreeHealth` row. Best-effort — a Convex
+   * blip should never block the reconcile path.
+   */
+  async reportHealth(args: {
+    pid: number;
+    fsType: string;
+    isFuse: boolean;
+    workspace: string;
+    lastReconcileFinishedAt: number;
+    lastFlushAt?: number;
+    onDiskCount: number;
+    activeBreakers: number;
+    pendingDrain: number;
+  }): Promise<void> {
+    await this.http.mutation(api.files.reportDaemonHealth, {
+      ...args,
+      apiKey: this.apiKey,
+    } as never);
+  }
+
   /**
    * Subscribe to fileTree updates for the org and invoke onChange whenever
    * a row's contentHash diverges from our local lastSyncedHash. The
@@ -505,6 +558,10 @@ async function runDaemon(daemonArgs: Args): Promise<void> {
     fsType: mount.fsType,
     isFuse: mount.isFuse,
   });
+  // Hook the writer to the live tracker so every status flush
+  // captures the current pending/in-flight counts. The flush
+  // subcommand polls these via the status file.
+  status.setDrainSnapshot(() => tracker.drainStatus());
   tracker.setBreakerListener((breakerState) => {
     status.recordBreakerEvent(breakerState);
     void status.flush();
@@ -580,9 +637,15 @@ async function runDaemon(daemonArgs: Args): Promise<void> {
       );
       const uploadUrl = await client.generateUploadUrl(posixPath);
       const storageId = await client.putBytes(uploadUrl, bytes);
+      // Only inline text for SMALL files that look like real UTF-8.
+      // Without the binary check, a 50KB PNG would get
+      // `TextDecoder({ fatal: false }).decode(bytes)`'d into a stream
+      // of U+FFFD replacement chars and persisted into
+      // `fileContents.text`, corrupting every viewer that hits the
+      // inline cache instead of the storage blob. See cli/fs-daemon-binary.ts.
       const inlineText =
         stats.size <= MAX_INLINE_TEXT_BYTES
-          ? new TextDecoder("utf-8", { fatal: false }).decode(bytes)
+          ? decodeInlineTextOrUndefined(bytes)
           : undefined;
       const result = await client.commitFileUpload({
         path: posixPath,
@@ -645,8 +708,10 @@ async function runDaemon(daemonArgs: Args): Promise<void> {
   // (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({
+  // the daemon is alive and what it last did. Also mirrors the
+  // heartbeat to Convex `fileTreeHealth` so the UI sidebar + chat-
+  // turn end-of-turn check can surface drift loudly.
+  const reconciler = startReconcileLoop({
     workspace: daemonArgs.workspace,
     intervalMs: reconcileIntervalMs,
     tracker,
@@ -669,10 +734,50 @@ async function runDaemon(daemonArgs: Args): Promise<void> {
         );
       }
     },
+    reportHealth: async (snapshot) => {
+      await client.reportHealth({
+        pid: process.pid,
+        fsType: mount.fsType,
+        isFuse: mount.isFuse,
+        workspace: daemonArgs.workspace,
+        lastReconcileFinishedAt: snapshot.finishedAt,
+        lastFlushAt: status.snapshot().lastFlushAt ?? undefined,
+        onDiskCount: snapshot.observed,
+        activeBreakers: snapshot.activeBreakers,
+        pendingDrain: snapshot.pendingDrain,
+      });
+    },
+  });
+
+  // SIGUSR1 = "flush requested" from `dench-fs-daemon flush` (chat-turn
+  // calls it after every execute_bash that touched /workspace). Run an
+  // immediate reconcile tick + record the flush completion timestamp so
+  // the polling caller can confirm the signal was honored. Errors are
+  // swallowed loudly into the daemon log; the flush command itself is
+  // responsible for surfacing timeouts.
+  process.on("SIGUSR1", () => {
+    const requestedAt = Date.now();
+    console.log(
+      `[dench-fs-daemon] SIGUSR1 received — running reconcile tick on demand`,
+    );
+    void reconciler
+      .runOneTick()
+      .catch((error) =>
+        console.error(
+          `[dench-fs-daemon] flush tick failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        ),
+      )
+      .then(() => {
+        status.recordFlushCompleted(requestedAt);
+        return status.flush();
+      })
+      .catch(() => undefined);
   });
 
   process.on("SIGTERM", () => {
-    stopReconcile();
+    reconciler.stop();
     unsubscribe();
     watcher.close().catch(() => undefined);
     process.exit(0);
@@ -742,6 +847,18 @@ async function snapshotWorkspace(
   return result;
 }
 
+type ReconcileLoopHandle = {
+  /** Tear down the periodic timers (called on SIGTERM). */
+  stop: () => void;
+  /**
+   * Run the reconcile body once on demand. Returned so the SIGUSR1
+   * handler can drain disk-only writes immediately without waiting
+   * for the next 5–30s tick — that's how `dench-fs-daemon flush`
+   * achieves its sub-second turnaround.
+   */
+  runOneTick: () => Promise<void>;
+};
+
 function startReconcileLoop(args: {
   workspace: string;
   intervalMs: number;
@@ -749,68 +866,129 @@ function startReconcileLoop(args: {
   status: DaemonStatusWriter;
   onLocalChange: (absPath: string) => void;
   onLocalDelete: (absPath: string) => Promise<void> | void;
-}): () => void {
+  /**
+   * Called once per tick (after the status file is flushed) to mirror
+   * the daemon health into Convex `fileTreeHealth`. Best-effort —
+   * Convex blips never block the reconcile path, but persistent
+   * failures get logged.
+   */
+  reportHealth?: (snapshot: {
+    finishedAt: number;
+    observed: number;
+    activeBreakers: number;
+    pendingDrain: number;
+  }) => Promise<void> | void;
+}): ReconcileLoopHandle {
   const last = new Map<string, FileSnapshot>();
 
   let stopped = false;
+  // Serialize concurrent ticks (SIGUSR1 + scheduled timer can race).
+  // The flush-driven tick can arrive milliseconds before the scheduled
+  // one; without serialization we'd double-walk the volume and the
+  // status file's `lastReconcile.finishedAt` would jitter
+  // backwards if writes interleave.
+  let inFlightTick: Promise<void> | null = null;
   const tick = async () => {
     if (stopped) return;
+    if (inFlightTick) {
+      await inFlightTick;
+      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++;
+    inFlightTick = (async () => {
+      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++;
+        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 {
+        const finishedAt = Date.now();
+        args.status.recordReconcile({
+          finishedAt,
+          durationMs: finishedAt - start,
+          observed,
+          scheduledForSync: scheduled,
+          deleted,
+          breakers: args.tracker.activeBreakers(),
+        });
+        await args.status.flush();
+        if (args.reportHealth) {
+          // Best-effort heartbeat into Convex `fileTreeHealth`. The
+          // chat-turn end-of-turn check + sidebar pill key off this
+          // row to surface "sync degraded" without polling the
+          // sandbox FS directly.
+          const drain = args.tracker.drainStatus();
+          try {
+            await args.reportHealth({
+              finishedAt,
+              observed,
+              activeBreakers: args.tracker.activeBreakers().length,
+              pendingDrain: drain.pendingPaths + drain.inFlightUploads,
+            });
+          } catch (error) {
+            console.error(
+              `[dench-fs-daemon] reportHealth failed: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            );
+          }
         }
       }
-      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)
-        }`,
-      );
+    })();
+    try {
+      await inFlightTick;
     } finally {
-      args.status.recordReconcile({
-        finishedAt: Date.now(),
-        durationMs: Date.now() - start,
-        observed,
-        scheduledForSync: scheduled,
-        deleted,
-        breakers: args.tracker.activeBreakers(),
-      });
-      await args.status.flush();
+      inFlightTick = null;
     }
   };
 
   // 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 initial = setTimeout(
+    () => {
+      void tick();
+    },
+    Math.min(args.intervalMs, 5_000),
+  );
   const interval = setInterval(() => {
     void tick();
   }, args.intervalMs);
 
-  return () => {
-    stopped = true;
-    clearTimeout(initial);
-    clearInterval(interval);
+  return {
+    stop: () => {
+      stopped = true;
+      clearTimeout(initial);
+      clearInterval(interval);
+    },
+    runOneTick: tick,
   };
 }
 
@@ -836,6 +1014,20 @@ type DaemonStatus = {
     scheduledForSync: number;
     deleted: number;
   } | null;
+  /**
+   * Wall-clock of the most recent SIGUSR1-driven flush request that
+   * the daemon completed. Used by `dench-fs-daemon flush` to confirm
+   * the daemon actually picked up the signal (not just that the
+   * scheduled reconcile tick happened to land afterwards).
+   */
+  lastFlushAt: number | null;
+  /**
+   * Mirror of `HashTracker.drainStatus()` taken at the same moment as
+   * `lastReconcile.finishedAt`. The flush poller waits for both
+   * counts to be zero AND `lastReconcile.finishedAt > t0` before
+   * declaring success.
+   */
+  pendingDrain: DrainStatus;
   activeBreakers: BreakerState[];
   recentBreakerEvents: BreakerState[];
 };
@@ -843,6 +1035,9 @@ type DaemonStatus = {
 class DaemonStatusWriter {
   private state: DaemonStatus;
   private writing: Promise<void> | null = null;
+  // Pulled at flush() time so the on-disk drain count tracks the live
+  // tracker without forcing every recordX() caller to plumb it through.
+  private drainSnapshotFn: (() => DrainStatus) | null = null;
 
   constructor(args: {
     workspace: string;
@@ -860,11 +1055,23 @@ class DaemonStatusWriter {
       fsType: args.fsType,
       isFuse: args.isFuse,
       lastReconcile: null,
+      lastFlushAt: null,
+      pendingDrain: { pendingPaths: 0, inFlightUploads: 0 },
       activeBreakers: [],
       recentBreakerEvents: [],
     };
   }
 
+  /**
+   * Wire up a callback the writer invokes inside `flush()` to grab
+   * the latest drain numbers off the live HashTracker. Kept as a
+   * snapshot fn (not a stored counter) so recordReconcile/breaker
+   * events don't have to thread the tracker through.
+   */
+  setDrainSnapshot(fn: () => DrainStatus): void {
+    this.drainSnapshotFn = fn;
+  }
+
   recordReconcile(args: {
     finishedAt: number;
     durationMs: number;
@@ -883,6 +1090,16 @@ class DaemonStatusWriter {
     this.state.activeBreakers = args.breakers;
   }
 
+  /**
+   * Mark a SIGUSR1 flush request as completed. Independent of
+   * recordReconcile because the same tick may be triggered by either
+   * the timer OR a flush signal — `lastFlushAt` proves the signal
+   * specifically was honored.
+   */
+  recordFlushCompleted(at: number): void {
+    this.state.lastFlushAt = at;
+  }
+
   recordBreakerEvent(state: BreakerState): void {
     const recent = [...this.state.recentBreakerEvents, state];
     // Cap at last 10 events so the file stays small.
@@ -892,6 +1109,9 @@ class DaemonStatusWriter {
 
   async flush(): Promise<void> {
     this.state.lastUpdatedAt = Date.now();
+    if (this.drainSnapshotFn) {
+      this.state.pendingDrain = this.drainSnapshotFn();
+    }
     const body = `${JSON.stringify(this.state, null, 2)}\n`;
     // Serialize so concurrent flushes don't interleave writes.
     const previous = this.writing ?? Promise.resolve();
@@ -904,6 +1124,15 @@ class DaemonStatusWriter {
       );
     await this.writing;
   }
+
+  /**
+   * Snapshot the current status state. Read-only — used by the
+   * reconcile loop's per-tick health heartbeat to Convex without
+   * forking a stale copy back into the writer.
+   */
+  snapshot(): Readonly<DaemonStatus> {
+    return this.state;
+  }
 }
 
 // ── Live streaming subcommands ─────────────────────────────────────────────
@@ -992,6 +1221,79 @@ async function runStreamClose(args: string[]): Promise<void> {
   await writeTokenStore(store);
 }
 
+// ── Flush subcommand ──────────────────────────────────────────────────────
+//
+// `dench-fs-daemon flush [--timeout-ms 5000]` blocks until the live
+// daemon has finished a reconcile tick AND drained every pending sync
+// timer + in-flight upload. Used by chat-turn after each `execute_bash`
+// that touched /workspace so the model sees Convex tree state that
+// matches what the bash command produced — no more 5s polling jitter
+// where files appear in the sidebar after the chat turn already
+// finished.
+//
+// Protocol:
+//   1. Read pid from /tmp/dench-fs-daemon.status.json.
+//   2. Send SIGUSR1 (the daemon's runDaemon registers a handler).
+//   3. Poll the status file every POLL_INTERVAL_MS until both
+//      a) `lastReconcile.finishedAt > t0`, AND
+//      b) `pendingDrain.pendingPaths === 0 && pendingDrain.inFlightUploads === 0`.
+//   4. Time out cleanly with exit 2 + the last-seen drain count so
+//      callers (chat-turn) can decide whether to surface drift.
+//
+// Exit codes: 0 ok, 1 no daemon, 2 timeout, 3 signal failed.
+//
+// The polling logic itself lives in `cli/fs-daemon-flush.ts` so the
+// unit tests can exercise it without booting the daemon.
+
+async function runFlush(argv: string[]): Promise<void> {
+  const timeoutIndex = argv.indexOf("--timeout-ms");
+  const parsedTimeout =
+    timeoutIndex === -1
+      ? FLUSH_DEFAULT_TIMEOUT_MS
+      : Number.parseInt(
+          argv[timeoutIndex + 1] ?? `${FLUSH_DEFAULT_TIMEOUT_MS}`,
+          10,
+        );
+  const timeoutMs = Number.isFinite(parsedTimeout)
+    ? parsedTimeout
+    : FLUSH_DEFAULT_TIMEOUT_MS;
+  const json = argv.includes("--json");
+
+  const outcome = await runFlushPolling({
+    timeoutMs,
+    readStatus: async () => (await readStatusFile()).state,
+    isPidAlive,
+    signal: (pid) => {
+      // process.kill with signal 'SIGUSR1' on Linux. On Darwin/local-dev
+      // the same call works for any node process; Windows lacks SIGUSR1
+      // but the daemon never runs there.
+      process.kill(pid, "SIGUSR1");
+    },
+  });
+
+  if (json) {
+    process.stdout.write(`${JSON.stringify(outcome)}\n`);
+  } else if (outcome.ok) {
+    process.stdout.write(
+      `DENCH_FS_FLUSH=ok pid=${outcome.pid} duration=${outcome.durationMs}ms\n`,
+    );
+  } else if (outcome.reason === "timeout") {
+    process.stderr.write(
+      `DENCH_FS_FLUSH=timeout pid=${outcome.pid} duration=${outcome.durationMs}ms pending=${outcome.drain.pendingPaths} inflight=${outcome.drain.inFlightUploads}\n`,
+    );
+  } else if (outcome.reason === "signal_failed") {
+    process.stderr.write(
+      `DENCH_FS_FLUSH=signal_failed pid=${outcome.pid} error=${outcome.error}\n`,
+    );
+  } else {
+    process.stderr.write(`DENCH_FS_FLUSH=no_daemon\n`);
+  }
+
+  if (outcome.ok) return;
+  process.exitCode =
+    outcome.reason === "no_daemon" ? 1 : outcome.reason === "timeout" ? 2 : 3;
+}
+
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
   const subcommand = argv[0];
@@ -1012,6 +1314,10 @@ async function main(): Promise<void> {
     await runInitialSync(argv.slice(1));
     return;
   }
+  if (subcommand === "flush") {
+    await runFlush(argv.slice(1));
+    return;
+  }
   if (subcommand === "status") {
     await runStatus(argv.slice(1));
     return;
@@ -1071,7 +1377,7 @@ async function runStatus(argv: string[]): Promise<void> {
   const workspaceIndex = argv.indexOf("--workspace");
   const workspace =
     workspaceIndex === -1
-      ? (process.env.DENCH_VOLUME_PATH?.trim() || "/workspace")
+      ? process.env.DENCH_VOLUME_PATH?.trim() || "/workspace"
       : (argv[workspaceIndex + 1] ?? "/workspace");
   const driftLimitIndex = argv.indexOf("--drift-limit");
   const driftLimit =
@@ -1080,7 +1386,11 @@ async function runStatus(argv: string[]): Promise<void> {
       : Math.max(0, Number.parseInt(argv[driftLimitIndex + 1] ?? "50", 10));
   const skipHash = argv.includes("--no-hash");
 
-  const report = await collectStatus({ workspace, driftLimit, hash: !skipHash });
+  const report = await collectStatus({
+    workspace,
+    driftLimit,
+    hash: !skipHash,
+  });
   if (json) {
     process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
     return;
@@ -1107,8 +1417,11 @@ async function collectStatus(args: {
   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 }> =
-    [];
+  let convexRows: Array<{
+    path: string;
+    contentHash?: string;
+    isDir: boolean;
+  }> = [];
   try {
     const snapshot = await snapshotWorkspace(args.workspace);
     for (const [absPath, info] of snapshot) {
@@ -1260,12 +1573,11 @@ async function readLogTail(lines: number): Promise<string[]> {
   }
 }
 
-async function collectConvexTree(client: DenchFileClient): Promise<
-  Array<{ path: string; contentHash?: string; isDir: boolean }>
-> {
+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 out: Array<{ path: string; contentHash?: string; isDir: boolean }> = [];
   const queue: string[] = ["/"];
   const seen = new Set<string>();
   while (queue.length > 0) {
@@ -1432,9 +1744,12 @@ async function runInitialSync(argv: string[]): Promise<void> {
         storageId,
         contentHash: hash,
         size: bytesBuf.byteLength,
+        // Same binary-aware inlining as scheduleSync — a fresh-volume
+        // initial sync that includes screenshots / PDFs / .zip would
+        // otherwise plant U+FFFD-corrupted text rows for every blob.
         text:
           bytesBuf.byteLength <= MAX_INLINE_TEXT_BYTES
-            ? new TextDecoder("utf-8", { fatal: false }).decode(bytesBuf)
+            ? decodeInlineTextOrUndefined(bytesBuf)
             : undefined,
         lastModifiedBy: "daemon",
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "cron.ts",
     "search.ts",
     "image.ts",
+    "tools.ts",
     "agentKind.ts",
     "host.ts",
     "openUrl.ts",