@dench.com/cli 0.4.1 → 0.4.2

package/chat-spawn.ts

@@ -17,6 +17,7 @@
  * calls until the workflow finishes.
  */
 
+import { getCurrentRuntimeTimeZone } from "@/lib/timezone";
 import { hasFlag } from "./lib/cli-args";
 
 class ChatSpawnError extends Error {}
@@ -64,12 +65,14 @@ async function postJson(
   bearer: string,
   body: unknown,
 ): Promise<{ ok: boolean; status: number; payload: unknown }> {
+  const timezone = getCurrentRuntimeTimeZone();
   const response = await fetch(url, {
     method: "POST",
     headers: {
       accept: "application/json",
       "content-type": "application/json",
       authorization: `Bearer ${bearer}`,
+      ...(timezone ? { "x-dench-user-timezone": timezone } : {}),
     },
     body: JSON.stringify(body),
   });
@@ -258,7 +261,10 @@ async function followStream(args: {
 }
 
 function joinPositionalsExceptFlags(args: string[]): string {
-  return args.filter((arg) => !arg.startsWith("--")).join(" ").trim();
+  return args
+    .filter((arg) => !arg.startsWith("--"))
+    .join(" ")
+    .trim();
 }
 
 async function runChatNew(ctx: ChatSpawnContext): Promise<void> {
@@ -286,6 +292,7 @@ async function runChatNew(ctx: ChatSpawnContext): Promise<void> {
       visibility,
       title,
       yolo,
+      timezone: getCurrentRuntimeTimeZone(),
     },
   );
   if (!result.ok) {
@@ -341,6 +348,7 @@ async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
       prompt,
       model,
       yolo,
+      timezone: getCurrentRuntimeTimeZone(),
     },
   );
   if (!result.ok) {
@@ -385,9 +393,7 @@ async function runChatFollow(ctx: ChatSpawnContext): Promise<void> {
   const positionals = ctx.args.filter((arg) => !arg.startsWith("--"));
   const threadId = positionals.shift();
   if (!threadId) {
-    throw new ChatSpawnError(
-      "Usage: dench chat follow <threadId> [--json]",
-    );
+    throw new ChatSpawnError("Usage: dench chat follow <threadId> [--json]");
   }
   if (!ctx.jsonOutput) {
     console.error(`--- following stream for thread ${threadId} ---`);

package/crm.ts

@@ -17,8 +17,8 @@
  * The full surface mirrors the plan's "dench-cli CRM surface" section:
  *   crm objects   list / get / create / update / delete / rename
  *   crm fields    list / create / update / delete / reorder
- *   crm entries   list / get / create / update / delete / bulk-delete
- *   crm cells     get / set / append
+ *   crm entries   list / get / create / create-many / update / update-many / delete / bulk-delete
+ *   crm cells     get / set / set-many / append
  *   crm query     <object> --where … --select … --sort … --limit …
  *   crm aggregate <object> --field …
  *   crm batch     --file ops.jsonl
@@ -40,6 +40,8 @@ import {
 
 type JsonRecord = Record<string, unknown>;
 
+const CRM_BATCH_CHUNK_SIZE = 200;
+
 type CrmCliContext = {
   convex: ConvexHttpClient;
   args: string[];
@@ -97,6 +99,150 @@ function getDataFlag(args: string[]): string | undefined {
   return getFlagWithAliases(args, "--data", ["--fields"]);
 }
 
+function getUpdatesFlag(args: string[]): string | undefined {
+  return getFlagWithAliases(args, "--updates", ["--data"]);
+}
+
+function isJsonRecord(value: unknown): value is JsonRecord {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function requireNonEmptyJsonRecord(value: unknown, label: string): JsonRecord {
+  if (!isJsonRecord(value) || Object.keys(value).length === 0) {
+    throw new CrmCliError(`${label} must be a non-empty JSON object`);
+  }
+  return value;
+}
+
+async function readJsonArrayInput(opts: {
+  args: string[];
+  command: string;
+  inlineFlag: string;
+  inlineValue: string | undefined;
+}): Promise<unknown[]> {
+  const filePath = getFlag(opts.args, "--file");
+  assertNoUnknownFlags(opts.args, opts.command);
+  if (opts.inlineValue !== undefined && filePath) {
+    throw new CrmCliError(
+      `${opts.command} accepts either ${opts.inlineFlag} or --file, not both`,
+    );
+  }
+  if (opts.inlineValue === undefined && !filePath) {
+    throw new CrmCliError(
+      `${opts.command} requires ${opts.inlineFlag} '<json-array>' or --file <path>`,
+    );
+  }
+
+  let raw: string;
+  if (filePath) {
+    const fs = await import("node:fs/promises");
+    raw = await fs.readFile(filePath, "utf-8");
+  } else {
+    raw = opts.inlineValue ?? "";
+  }
+
+  const parsed = parseJson(raw);
+  if (!Array.isArray(parsed)) {
+    throw new CrmCliError(`${opts.inlineFlag} must be a JSON array`);
+  }
+  if (parsed.length === 0) {
+    throw new CrmCliError(`${opts.inlineFlag} must include at least one item`);
+  }
+  return parsed;
+}
+
+function parseCreateManyRows(items: unknown[]): JsonRecord[] {
+  return items.map((item, index) =>
+    requireNonEmptyJsonRecord(item, `create-many item ${index + 1}`),
+  );
+}
+
+function parseUpdateManyRows(items: unknown[]): Array<{
+  id: string;
+  data: JsonRecord;
+}> {
+  return items.map((item, index) => {
+    if (!isJsonRecord(item) || typeof item.id !== "string" || !item.id) {
+      throw new CrmCliError(
+        `update-many item ${index + 1} must include a string id`,
+      );
+    }
+    return {
+      id: item.id,
+      data: requireNonEmptyJsonRecord(
+        item.data,
+        `update-many item ${index + 1} data`,
+      ),
+    };
+  });
+}
+
+function parseCellSetManyRows(items: unknown[]): Array<{
+  entryId: string;
+  field: string;
+  value: unknown;
+}> {
+  return items.map((item, index) => {
+    if (!isJsonRecord(item)) {
+      throw new CrmCliError(
+        `cells set-many item ${index + 1} must be a JSON object`,
+      );
+    }
+    if (typeof item.entryId !== "string" || !item.entryId) {
+      throw new CrmCliError(
+        `cells set-many item ${index + 1} must include a string entryId`,
+      );
+    }
+    if (typeof item.field !== "string" || !item.field) {
+      throw new CrmCliError(
+        `cells set-many item ${index + 1} must include a string field`,
+      );
+    }
+    return {
+      entryId: item.entryId,
+      field: item.field,
+      value: item.value ?? null,
+    };
+  });
+}
+
+type CrmBatchOp =
+  | { type: "entries.create"; objectName: string; data: JsonRecord }
+  | { type: "entries.update"; entryId: string; data: JsonRecord };
+
+function chunkArray<T>(items: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let index = 0; index < items.length; index += size) {
+    chunks.push(items.slice(index, index + size));
+  }
+  return chunks;
+}
+
+function chunkIdempotencyKey(
+  idempotencyKey: string | undefined,
+  chunkIndex: number,
+): string | undefined {
+  return idempotencyKey
+    ? `${idempotencyKey}:chunk-${chunkIndex + 1}`
+    : undefined;
+}
+
+async function applyBatchOpsInChunks(
+  ctx: CrmCliContext,
+  ops: CrmBatchOp[],
+  idempotencyKey: string | undefined,
+): Promise<number> {
+  const chunks = chunkArray(ops, CRM_BATCH_CHUNK_SIZE);
+  for (const [chunkIndex, chunk] of chunks.entries()) {
+    const chunkKey = chunkIdempotencyKey(idempotencyKey, chunkIndex);
+    await callMutation(ctx, api.batch.apply, {
+      ops: chunk,
+      ...(chunkKey ? { idempotencyKey: chunkKey } : {}),
+    });
+  }
+  return chunks.length;
+}
+
 async function callQuery(
   ctx: CrmCliContext,
   fn: Parameters<ConvexHttpClient["query"]>[0],
@@ -139,6 +285,35 @@ function out(ctx: CrmCliContext, value: unknown): void {
   console.log(JSON.stringify(value, null, 2));
 }
 
+function getFieldEnrichmentFlag(args: string[]): {
+  category: EnrichmentCategory;
+  key: string;
+  apolloPath: string;
+  inputFieldName: string;
+} | undefined {
+  const category = parseCategoryFlag(getFlag(args, "--enrichment-category"));
+  const key = getFlag(args, "--enrichment-key");
+  const apolloPath = getFlag(args, "--apollo-path");
+  const inputFieldName = getFlag(args, "--input-field");
+  const sawAny =
+    category !== undefined ||
+    key !== undefined ||
+    apolloPath !== undefined ||
+    inputFieldName !== undefined;
+  if (!sawAny) return undefined;
+  if (!category || !apolloPath || !inputFieldName) {
+    throw new CrmCliError(
+      "Enrichment fields require --enrichment-category people|company, --apollo-path <path>, and --input-field <field>.",
+    );
+  }
+  return {
+    category,
+    key: key ?? apolloPath,
+    apolloPath,
+    inputFieldName,
+  };
+}
+
 const api = {
   transaction: {
     begin: makeFunctionReference<"mutation">("functions/crm/transaction:begin"),
@@ -380,6 +555,7 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
         : hasFlag(ctx.args, "--no-indexed")
           ? false
           : undefined;
+      const enrichment = getFieldEnrichmentFlag(ctx.args);
       assertNoUnknownFlags(ctx.args, "crm fields create");
       out(
         ctx,
@@ -395,6 +571,7 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
           relatedObjectName,
           relationshipType,
           indexed,
+          enrichment,
         }),
       );
       return;
@@ -412,6 +589,8 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
         : hasFlag(ctx.args, "--no-indexed")
           ? false
           : undefined;
+      const enrichment = getFieldEnrichmentFlag(ctx.args);
+      const clearEnrichment = hasFlag(ctx.args, "--clear-enrichment");
       assertNoUnknownFlags(ctx.args, "crm fields update");
       out(
         ctx,
@@ -422,6 +601,8 @@ async function runFieldsCommand(ctx: CrmCliContext): Promise<void> {
           required,
           enumValues,
           indexed,
+          enrichment,
+          clearEnrichment,
         }),
       );
       return;
@@ -509,6 +690,30 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       );
       return;
     }
+    case "create-many": {
+      const objectName = shift(ctx.args, "object name");
+      const dataRaw = getDataFlag(ctx.args);
+      const idempotencyKey = getFlag(ctx.args, "--idempotency-key");
+      const rows = parseCreateManyRows(
+        await readJsonArrayInput({
+          args: ctx.args,
+          command: "crm entries create-many",
+          inlineFlag: "--data",
+          inlineValue: dataRaw,
+        }),
+      );
+      const chunks = await applyBatchOpsInChunks(
+        ctx,
+        rows.map((data) => ({
+          type: "entries.create",
+          objectName,
+          data,
+        })),
+        idempotencyKey,
+      );
+      out(ctx, { created: rows.length, chunks });
+      return;
+    }
     case "update": {
       const objectName = shift(ctx.args, "object name");
       const entryId = shift(ctx.args, "entry id");
@@ -535,6 +740,30 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
       );
       return;
     }
+    case "update-many": {
+      const _objectName = shift(ctx.args, "object name");
+      const updatesRaw = getUpdatesFlag(ctx.args);
+      const idempotencyKey = getFlag(ctx.args, "--idempotency-key");
+      const updates = parseUpdateManyRows(
+        await readJsonArrayInput({
+          args: ctx.args,
+          command: "crm entries update-many",
+          inlineFlag: "--updates",
+          inlineValue: updatesRaw,
+        }),
+      );
+      const chunks = await applyBatchOpsInChunks(
+        ctx,
+        updates.map((update) => ({
+          type: "entries.update",
+          entryId: update.id,
+          data: update.data,
+        })),
+        idempotencyKey,
+      );
+      out(ctx, { updated: updates.length, chunks });
+      return;
+    }
     case "delete":
     case "remove": {
       const _objectName = shift(ctx.args, "object name");
@@ -569,11 +798,11 @@ async function runEntriesCommand(ctx: CrmCliContext): Promise<void> {
 
 async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
   const verb = ctx.args.shift();
-  const objectName = shift(ctx.args, "object name");
-  const entryId = shift(ctx.args, "entry id");
-  const fieldName = shift(ctx.args, "field name");
   switch (verb) {
     case "get": {
+      const objectName = shift(ctx.args, "object name");
+      const entryId = shift(ctx.args, "entry id");
+      const fieldName = shift(ctx.args, "field name");
       assertNoUnknownFlags(ctx.args, "crm cells get");
       out(
         ctx,
@@ -586,6 +815,9 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
       return;
     }
     case "set": {
+      const objectName = shift(ctx.args, "object name");
+      const entryId = shift(ctx.args, "entry id");
+      const fieldName = shift(ctx.args, "field name");
       const value = parseJson(ctx.args.shift()) ?? null;
       assertNoUnknownFlags(ctx.args, "crm cells set");
       out(
@@ -599,7 +831,39 @@ async function runCellsCommand(ctx: CrmCliContext): Promise<void> {
       );
       return;
     }
+    case "set-many": {
+      const _objectName = shift(ctx.args, "object name");
+      const updatesRaw = getUpdatesFlag(ctx.args);
+      const idempotencyKey = getFlag(ctx.args, "--idempotency-key");
+      const updates = parseCellSetManyRows(
+        await readJsonArrayInput({
+          args: ctx.args,
+          command: "crm cells set-many",
+          inlineFlag: "--updates",
+          inlineValue: updatesRaw,
+        }),
+      );
+      const grouped = new Map<string, JsonRecord>();
+      for (const update of updates) {
+        const data = grouped.get(update.entryId) ?? {};
+        data[update.field] = update.value;
+        grouped.set(update.entryId, data);
+      }
+      const ops: CrmBatchOp[] = Array.from(grouped.entries()).map(
+        ([entryId, data]) => ({
+          type: "entries.update",
+          entryId,
+          data,
+        }),
+      );
+      const chunks = await applyBatchOpsInChunks(ctx, ops, idempotencyKey);
+      out(ctx, { updated: updates.length, entriesUpdated: ops.length, chunks });
+      return;
+    }
     case "append": {
+      const objectName = shift(ctx.args, "object name");
+      const entryId = shift(ctx.args, "entry id");
+      const fieldName = shift(ctx.args, "field name");
       const value = parseJson(ctx.args.shift()) ?? null;
       assertNoUnknownFlags(ctx.args, "crm cells append");
       out(
@@ -1431,8 +1695,9 @@ Fields (columns):
   dench crm fields create <object> <name> --type text|email|phone|url|number|boolean|date|enum|relation|user|tags|action|file|richtext \\
         [--required] [--description ...] [--enum-values JSON] [--enum-colors JSON] \\
         [--enum-multiple] [--related-object <name>] [--relationship many_to_one|many_to_many] \\
-        [--indexed | --no-indexed]
-  dench crm fields update <object> <field> [--description ...] [--required] [--enum-values JSON] [--indexed | --no-indexed]
+        [--indexed | --no-indexed] [--enrichment-category people|company --apollo-path <path> --input-field <field>]
+  dench crm fields update <object> <field> [--description ...] [--required] [--enum-values JSON] [--indexed | --no-indexed] \\
+        [--enrichment-category people|company --apollo-path <path> --input-field <field> | --clear-enrichment]
   dench crm fields delete <object> <field>
   dench crm fields reorder <object> <field1> <field2> <field3> ...
 
@@ -1440,7 +1705,9 @@ Entries (rows):
   dench crm entries list <object> [--limit N] [--json]
   dench crm entries get <object> <entryId>
   dench crm entries create <object> --data '{"Field":"Value",...}'    (alias: --fields)
+  dench crm entries create-many <object> --data '[{"Field":"Value",...}]' [--file rows.json] [--idempotency-key <key>]
   dench crm entries update <object> <entryId> --data '{...}'           (alias: --fields)
+  dench crm entries update-many <object> --updates '[{"id":"...","data":{...}}]' [--file updates.json] [--idempotency-key <key>]
   dench crm entries delete <object> <entryId>
   dench crm entries bulk-delete <object> --ids id1,id2,id3
   Note: --data is REQUIRED on create/update and must include >=1 field.
@@ -1450,6 +1717,7 @@ Entries (rows):
 Cells (single-field updates):
   dench crm cells get <object> <entryId> <field>
   dench crm cells set <object> <entryId> <field> '<JSON value>'
+  dench crm cells set-many <object> --updates '[{"entryId":"...","field":"Status","value":"Done"}]' [--file updates.json] [--idempotency-key <key>]
   dench crm cells append <object> <entryId> <field> '<JSON value>'
 
 Query DSL:
@@ -1467,6 +1735,9 @@ Statuses (kanban columns):
 
 Batch:
   dench crm batch --file ops.jsonl [--idempotency-key <key>]
+  For repeated writes, prefer entries create-many/update-many or cells set-many;
+  for transformations, write a script in /tmp/work/<runId>/ that loops locally
+  and calls a batch surface in chunks.
 
 Import / export:
   dench crm import <object> --csv leads.csv [--map '{"Email":"Email Address"}'] [--on-conflict skip|update|error]

package/dench.ts

@@ -447,8 +447,9 @@ Usage:
 CRM (Daytona-native rewrite):
   dench crm objects <list|get|create|update|rename|delete> ...
   dench crm fields <list|create|update|delete|reorder> <object> ...
-  dench crm entries <list|get|create|update|delete|bulk-delete> <object> ...
+  dench crm entries <list|get|create|create-many|update|update-many|delete|bulk-delete> <object> ...
   dench crm cells <get|set|append> <object> <entryId> <field> [value]
+  dench crm cells set-many <object> --updates '[...]'
   dench crm query <object> --where '...' --select ... --sort ... --limit N
   dench crm sql 'SELECT "Name" FROM lead WHERE ... LIMIT 10'
   dench crm aggregate <object> --field <name>
@@ -462,6 +463,7 @@ CRM (Daytona-native rewrite):
   dench crm docs <list|create|link>
   dench crm actions <list|run> ...
   dench crm batch --file ops.jsonl
+  Batch write helpers: entries create-many/update-many, cells set-many
   Help: dench crm help
 
 Live web search (Exa via the Dench Cloud Gateway, auths with DENCH_API_KEY):

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.1",
+  "version": "0.4.2",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {