@dench.com/cli 0.4.3 → 0.4.4

package/chat.ts

@@ -119,10 +119,10 @@ function chatHelp(): void {
   console.log(`Usage: dench chat <subcommand>
 
 List past chat threads (own + shared in this workspace):
-  dench chat list [--query <substr>] [--limit N] [--include-archived] [--json]
+  dench chat list [--query <substr>] [--limit N] [--include-archived] [--include-automated] [--json]
 
 Full-text search across past chat messages (own + shared):
-  dench chat search "<query>" [--limit N] [--include-current] [--json]
+  dench chat search "<query>" [--limit N] [--include-current] [--include-automated] [--json]
 
 Read messages from a specific past chat thread:
   dench chat read <thread-id> [--limit N] [--json]
@@ -134,12 +134,20 @@ Rename one or more past chat threads (own + shared):
     Up to 50 items per call. Titles are trimmed and clamped to 200 chars.
 
 PERMANENTLY delete one or more past chat threads (and all their messages):
-  dench chat delete <thread-id> [<thread-id>...] [--yes] [--json]
-  dench chat delete --ids id1,id2,id3 [--yes] [--json]
+  dench chat delete <thread-id> [<thread-id>...] [--yes] [--include-automated] [--json]
+  dench chat delete --ids id1,id2,id3 [--yes] [--include-automated] [--json]
     Up to 25 ids per call. IRREVERSIBLE — the messages are removed too.
     Without --yes, the CLI prompts for confirmation when stdin is a TTY.
     In non-interactive contexts (sandboxes, scripts), --yes is required.
 
+    Fire-and-forget: deletion runs in the background. The CLI returns
+    \`{scheduled, rejected, total}\` immediately; threads disappear from
+    the sidebar live as each per-thread mutation completes.
+
+    AUTOMATION THREADS PROTECTED: cron-spawned routine threads and
+    heartbeat ticks are filtered out of \`list\` / \`search\` and the
+    server REFUSES to delete them unless \`--include-automated\` is set.
+
 Spawn a new chat-turn workflow (same agent loop as the web UI):
   dench chat new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
   dench chat send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
@@ -209,18 +217,21 @@ async function runChatListCommand(ctx: ChatCliContext): Promise<void> {
   const titleQuery = getFlag(ctx.args, "--query");
   const limit = parseLimit(getFlag(ctx.args, "--limit"));
   const includeArchived = hasFlag(ctx.args, "--include-archived");
+  const includeAutomated = hasFlag(ctx.args, "--include-automated");
   out(
     ctx,
     await callQuery(ctx, api.listPastChats, {
       titleQuery,
       limit,
       includeArchived,
+      includeAutomated,
     }),
   );
 }
 
 async function runChatSearchCommand(ctx: ChatCliContext): Promise<void> {
   const includeCurrent = hasFlag(ctx.args, "--include-current");
+  const includeAutomated = hasFlag(ctx.args, "--include-automated");
   const limit = parseLimit(getFlag(ctx.args, "--limit"));
   const queryParts: string[] = [];
   while (ctx.args.length > 0) {
@@ -231,7 +242,7 @@ async function runChatSearchCommand(ctx: ChatCliContext): Promise<void> {
   const query = queryParts.join(" ").trim();
   if (!query) {
     throw new ChatCliError(
-      'Usage: dench chat search "<query>" [--limit N] [--include-current]',
+      'Usage: dench chat search "<query>" [--limit N] [--include-current] [--include-automated]',
     );
   }
   out(
@@ -239,6 +250,7 @@ async function runChatSearchCommand(ctx: ChatCliContext): Promise<void> {
     await callQuery(ctx, api.searchPastChats, {
       query,
       limit,
+      includeAutomated,
       // The server defaults excludeThreadId to undefined; the agent path
       // sets it explicitly. CLI users are not "in" a thread, so we pass
       // undefined unless --include-current is intentionally set (no-op).
@@ -378,6 +390,7 @@ async function promptYesNo(question: string): Promise<boolean> {
 async function runChatDeleteCommand(ctx: ChatCliContext): Promise<void> {
   const idsFlag = getFlag(ctx.args, "--ids");
   const skipConfirm = hasFlag(ctx.args, "--yes") || hasFlag(ctx.args, "-y");
+  const includeAutomated = hasFlag(ctx.args, "--include-automated");
   const collected: string[] = [];
   if (idsFlag) {
     for (const part of idsFlag.split(",")) {
@@ -405,6 +418,9 @@ async function runChatDeleteCommand(ctx: ChatCliContext): Promise<void> {
       "Usage: dench chat delete <thread-id> [<thread-id>...]  (or --ids id1,id2,...)",
     );
   }
+  // Server caps each call at 25 ids. Each accepted id is scheduled for
+  // background deletion (fire-and-forget), so the cap exists to bound
+  // the per-call validation work, not the deletion volume itself.
   if (threadIds.length > 25) {
     throw new ChatCliError(
       `Too many thread ids (${threadIds.length}); the server caps each call at 25. Run multiple invocations.`,
@@ -416,17 +432,26 @@ async function runChatDeleteCommand(ctx: ChatCliContext): Promise<void> {
         "Refusing to delete without --yes in non-interactive mode (no TTY).",
       );
     }
+    const automatedSuffix = includeAutomated
+      ? " (INCLUDING ROUTINES / HEARTBEATS — automated thread protection bypassed)"
+      : "";
     const ok = await promptYesNo(
-      `PERMANENTLY delete ${threadIds.length} chat${
+      `PERMANENTLY queue delete of ${threadIds.length} chat${
         threadIds.length === 1 ? "" : "s"
-      } and all their messages?`,
+      } and all their messages${automatedSuffix}?`,
     );
     if (!ok) {
       console.error("Aborted.");
       return;
     }
   }
-  out(ctx, await callMutation(ctx, api.deleteThreads, { threadIds }));
+  out(
+    ctx,
+    await callMutation(ctx, api.deleteThreads, {
+      threadIds,
+      includeAutomated,
+    }),
+  );
 }
 
 /**

package/crm.ts

@@ -37,6 +37,21 @@ import {
   parseJson as parseJsonRaw,
   shift as shiftRaw,
 } from "./lib/cli-args";
+import {
+  autoDetectInputField,
+  detectEnrichmentCategory,
+  extractEnrichmentValue,
+  findEnrichmentColumn,
+  getRequiredFieldsForApolloPath,
+  type EnrichmentCategory,
+  type EnrichmentColumnDef,
+  type FieldCandidate,
+} from "./lib/crm-enrichment";
+import {
+  enrichCompany,
+  EnrichmentGatewayError,
+  enrichPersonByIdentifier,
+} from "./lib/enrichment-gateway";
 
 type JsonRecord = Record<string, unknown>;
 
@@ -333,6 +348,9 @@ const api = {
     requestCellEnrichment: makeFunctionReference<"mutation">(
       "functions/crm/enrich:requestCellEnrichment",
     ),
+    applyCellEnrichmentResult: makeFunctionReference<"mutation">(
+      "functions/crm/enrich:applyCellEnrichmentResult",
+    ),
     requestObjectEnrichment: makeFunctionReference<"mutation">(
       "functions/crm/enrich:requestObjectEnrichment",
     ),
@@ -1463,6 +1481,334 @@ async function runSqlCommand(ctx: CrmCliContext): Promise<void> {
   );
 }
 
+// ── CRM enrichment gateway orchestration ─────────────────────────────────
+
+type CrmFieldForEnrichment = FieldCandidate & {
+  defaultValue?: string;
+  enrichment?: {
+    category: EnrichmentCategory;
+    key: string;
+    apolloPath: string;
+    inputFieldName: string;
+  };
+};
+
+type CrmEntryForEnrichment = {
+  id: string;
+  fields: Record<string, unknown>;
+};
+
+type EnrichmentTarget = {
+  category: EnrichmentCategory;
+  column: EnrichmentColumnDef;
+  requiredFields: string[];
+  inputField: CrmFieldForEnrichment;
+};
+
+type CellEnrichmentArgs = {
+  objectName: string;
+  entryId: string;
+  fieldName: string;
+  provider?: string;
+  category?: EnrichmentCategory;
+  inputFieldName?: string;
+  apolloPath?: string;
+  overwrite?: boolean;
+};
+
+type ObjectEnrichmentArgs = Omit<CellEnrichmentArgs, "entryId"> & {
+  missingOnly: boolean;
+  limit?: number;
+};
+
+function parseCategoryFlag(value: string | undefined): EnrichmentCategory | undefined {
+  if (value === undefined) return undefined;
+  if (value === "people" || value === "company") return value;
+  throw new CrmCliError("--category must be people or company");
+}
+
+function parsePositiveInt(flag: string, value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new CrmCliError(`${flag} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function hasCellValue(value: unknown): boolean {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function asFields(value: unknown): CrmFieldForEnrichment[] {
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((field): field is CrmFieldForEnrichment => {
+      if (!field || typeof field !== "object") return false;
+      const candidate = field as Record<string, unknown>;
+      return typeof candidate.name === "string" && typeof candidate.type === "string";
+    })
+    .map((field) => ({
+      id: typeof field.id === "string" ? field.id : undefined,
+      name: field.name,
+      type: field.type,
+      defaultValue:
+        typeof field.defaultValue === "string" ? field.defaultValue : undefined,
+      enrichment: readFieldEnrichment(field),
+    }));
+}
+
+function readFieldEnrichment(
+  field: Record<string, unknown>,
+): CrmFieldForEnrichment["enrichment"] {
+  const enrichment = field.enrichment;
+  if (!enrichment || typeof enrichment !== "object") return undefined;
+  const candidate = enrichment as Record<string, unknown>;
+  const category = parseCategoryFlag(
+    typeof candidate.category === "string" ? candidate.category : undefined,
+  );
+  const key = typeof candidate.key === "string" ? candidate.key : undefined;
+  const apolloPath =
+    typeof candidate.apolloPath === "string" ? candidate.apolloPath : undefined;
+  const inputFieldName =
+    typeof candidate.inputFieldName === "string"
+      ? candidate.inputFieldName
+      : undefined;
+  if (!category || !key || !apolloPath || !inputFieldName) return undefined;
+  return { category, key, apolloPath, inputFieldName };
+}
+
+function asEntry(value: unknown): CrmEntryForEnrichment | null {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate.id !== "string") return null;
+  const fields =
+    candidate.fields && typeof candidate.fields === "object"
+      ? (candidate.fields as Record<string, unknown>)
+      : {};
+  return { id: candidate.id, fields };
+}
+
+function asEntries(value: unknown): CrmEntryForEnrichment[] {
+  if (!Array.isArray(value)) return [];
+  return value.map(asEntry).filter((entry): entry is CrmEntryForEnrichment => !!entry);
+}
+
+function resolveEnrichmentColumn(args: {
+  category: EnrichmentCategory;
+  fieldName: string;
+  apolloPath?: string;
+}): EnrichmentColumnDef {
+  const catalogColumn = findEnrichmentColumn({
+    category: args.category,
+    apolloPath: args.apolloPath,
+    label: args.apolloPath ? undefined : args.fieldName,
+    key: args.apolloPath ? undefined : args.fieldName,
+  });
+  if (catalogColumn) return catalogColumn;
+  if (args.apolloPath) {
+    return {
+      label: args.fieldName,
+      key: args.apolloPath,
+      fieldType: "text",
+      apolloPath: args.apolloPath,
+      requiredFields: getRequiredFieldsForApolloPath(
+        args.category,
+        args.apolloPath,
+      ),
+    };
+  }
+  throw new CrmCliError(
+    `No enrichment catalog column found for "${args.fieldName}". Pass --apollo-path for a custom gateway response path.`,
+  );
+}
+
+async function resolveEnrichmentTarget(
+  ctx: CrmCliContext,
+  args: {
+    objectName: string;
+    fieldName: string;
+    category?: EnrichmentCategory;
+    inputFieldName?: string;
+    apolloPath?: string;
+  },
+): Promise<EnrichmentTarget> {
+  const fields = asFields(
+    await callQuery(ctx, api.fields.list, { objectName: args.objectName }),
+  );
+  const outputField = fields.find((field) => field.name === args.fieldName);
+  if (!outputField) {
+    throw new CrmCliError(`Field "${args.fieldName}" not found`);
+  }
+
+  const category =
+    args.category ??
+    outputField.enrichment?.category ??
+    detectEnrichmentCategory(args.objectName) ??
+    undefined;
+  if (!category) {
+    throw new CrmCliError(
+      "Could not infer enrichment category. Pass --category people|company.",
+    );
+  }
+
+  const column = resolveEnrichmentColumn({
+    category,
+    fieldName: args.fieldName,
+    apolloPath: args.apolloPath ?? outputField.enrichment?.apolloPath,
+  });
+
+  const inputFieldName = args.inputFieldName ?? outputField.enrichment?.inputFieldName;
+  const inputField = inputFieldName
+    ? fields.find((field) => field.name === inputFieldName)
+    : autoDetectInputField(category, fields);
+  if (!inputField) {
+    throw new CrmCliError(
+      inputFieldName
+        ? `Input field "${inputFieldName}" not found`
+        : "Could not infer input field. Pass --input-field <field>.",
+    );
+  }
+
+  return {
+    category,
+    column,
+    requiredFields: column.requiredFields,
+    inputField,
+  };
+}
+
+async function callEnrichmentGatewayForEntry(args: {
+  target: EnrichmentTarget;
+  entry: CrmEntryForEnrichment;
+}): Promise<Record<string, unknown>> {
+  const input = args.entry.fields[args.target.inputField.name];
+  if (!hasCellValue(input)) {
+    throw new CrmCliError(
+      `Entry ${args.entry.id} has no value for input field "${args.target.inputField.name}"`,
+    );
+  }
+  const inputValue = String(input);
+  if (args.target.category === "people") {
+    return await enrichPersonByIdentifier(inputValue, args.target.requiredFields);
+  }
+  return await enrichCompany({
+    domain: inputValue,
+    requiredFields: args.target.requiredFields,
+  });
+}
+
+async function enrichOneEntry(
+  ctx: CrmCliContext,
+  args: CellEnrichmentArgs & {
+    target: EnrichmentTarget;
+    entry: CrmEntryForEnrichment;
+  },
+): Promise<Record<string, unknown>> {
+  try {
+    const payload = await callEnrichmentGatewayForEntry({
+      target: args.target,
+      entry: args.entry,
+    });
+    const value = extractEnrichmentValue(payload, args.target.column);
+    if (value === null) {
+      return {
+        entryId: args.entry.id,
+        ok: false,
+        reason: "value_not_found",
+      };
+    }
+    const writeResult = (await callMutation(
+      ctx,
+      api.enrich.applyCellEnrichmentResult,
+      {
+        objectName: args.objectName,
+        entryId: args.entry.id,
+        fieldName: args.fieldName,
+        value,
+        provider: args.provider ?? "gateway",
+        overwrite: args.overwrite,
+      },
+    )) as Record<string, unknown>;
+    return {
+      entryId: args.entry.id,
+      ok: writeResult.ok === true,
+      value,
+      ...writeResult,
+    };
+  } catch (error) {
+    if (error instanceof EnrichmentGatewayError || error instanceof CrmCliError) {
+      return {
+        entryId: args.entry.id,
+        ok: false,
+        reason:
+          error instanceof EnrichmentGatewayError
+            ? (error.code ?? "enrichment_failed")
+            : "enrichment_failed",
+        message: error.message,
+      };
+    }
+    throw error;
+  }
+}
+
+async function enrichCellThroughGateway(
+  ctx: CrmCliContext,
+  args: CellEnrichmentArgs,
+): Promise<Record<string, unknown>> {
+  const target = await resolveEnrichmentTarget(ctx, args);
+  const entry = asEntry(
+    await callQuery(ctx, api.entries.get, {
+      objectName: args.objectName,
+      entryId: args.entryId,
+    }),
+  );
+  if (!entry) throw new CrmCliError("Entry not found");
+  const result = await enrichOneEntry(ctx, { ...args, target, entry });
+  return {
+    objectName: args.objectName,
+    fieldName: args.fieldName,
+    inputFieldName: target.inputField.name,
+    category: target.category,
+    apolloPath: target.column.apolloPath,
+    result,
+  };
+}
+
+async function enrichObjectThroughGateway(
+  ctx: CrmCliContext,
+  args: ObjectEnrichmentArgs,
+): Promise<Record<string, unknown>> {
+  const target = await resolveEnrichmentTarget(ctx, args);
+  const entries = asEntries(
+    await callQuery(ctx, api.entries.list, {
+      objectName: args.objectName,
+      limit: args.limit ?? 100,
+    }),
+  );
+  const selected = entries.filter((entry) => {
+    if (!args.missingOnly) return true;
+    return !hasCellValue(entry.fields[args.fieldName]);
+  });
+  const results: Record<string, unknown>[] = [];
+  for (const entry of selected) {
+    results.push(await enrichOneEntry(ctx, { ...args, target, entry }));
+  }
+  return {
+    objectName: args.objectName,
+    fieldName: args.fieldName,
+    inputFieldName: target.inputField.name,
+    category: target.category,
+    apolloPath: target.column.apolloPath,
+    total: entries.length,
+    selected: selected.length,
+    enriched: results.filter((result) => result.ok === true).length,
+    skipped: entries.length - selected.length,
+    failed: results.filter((result) => result.ok !== true).length,
+    results,
+  };
+}
+
 // ── People + companies shortcuts ─────────────────────────────────────────
 //
 // These are thin wrappers around the standard objects/entries surface,
@@ -1511,20 +1857,22 @@ async function runPeopleCommand(ctx: CrmCliContext): Promise<void> {
     case "enrich": {
       const entryId = shift(ctx.args, "person entry id");
       const provider = getFlag(ctx.args, "--provider");
-      const fieldName = getFlag(ctx.args, "--field") ?? "Email Address";
+      const fieldName = getFlag(ctx.args, "--field") ?? "LinkedIn URL";
+      const inputFieldName = getFlag(ctx.args, "--input-field");
+      const overwrite = hasFlag(ctx.args, "--overwrite");
       assertNoUnknownFlags(ctx.args, "crm people enrich");
       out(
         ctx,
-        await callMutation(ctx, api.enrich.requestObjectEnrichment, {
+        await enrichCellThroughGateway(ctx, {
           objectName: "people",
+          entryId,
           fieldName,
           provider,
+          category: "people",
+          inputFieldName,
+          overwrite,
         }),
       );
-      // Don't reference entryId in the request — Phase 3 v1 enrichment is
-      // object-level only; cell-level lands once gateway enrichment ships.
-      // Print entryId in the result so the caller has context.
-      out(ctx, { entryId });
       return;
     }
     default:
@@ -1573,17 +1921,22 @@ async function runCompaniesCommand(ctx: CrmCliContext): Promise<void> {
     case "enrich": {
       const entryId = shift(ctx.args, "company entry id");
       const provider = getFlag(ctx.args, "--provider");
-      const fieldName = getFlag(ctx.args, "--field") ?? "Domain";
+      const fieldName = getFlag(ctx.args, "--field") ?? "Company Name";
+      const inputFieldName = getFlag(ctx.args, "--input-field") ?? "Domain";
+      const overwrite = hasFlag(ctx.args, "--overwrite");
       assertNoUnknownFlags(ctx.args, "crm companies enrich");
       out(
         ctx,
-        await callMutation(ctx, api.enrich.requestObjectEnrichment, {
+        await enrichCellThroughGateway(ctx, {
           objectName: "company",
+          entryId,
           fieldName,
           provider,
+          category: "company",
+          inputFieldName,
+          overwrite,
         }),
       );
-      out(ctx, { entryId });
       return;
     }
     default:
@@ -1601,14 +1954,22 @@ async function runEnrichCommand(ctx: CrmCliContext): Promise<void> {
       const entryId = shift(ctx.args, "entry id");
       const fieldName = shift(ctx.args, "field name");
       const provider = getFlag(ctx.args, "--provider");
+      const inputFieldName = getFlag(ctx.args, "--input-field");
+      const category = parseCategoryFlag(getFlag(ctx.args, "--category"));
+      const apolloPath = getFlag(ctx.args, "--apollo-path");
+      const overwrite = hasFlag(ctx.args, "--overwrite");
       assertNoUnknownFlags(ctx.args, "crm enrich cell");
       out(
         ctx,
-        await callMutation(ctx, api.enrich.requestCellEnrichment, {
+        await enrichCellThroughGateway(ctx, {
           objectName,
-          entryId: entryId as any,
+          entryId,
           fieldName,
           provider,
+          category,
+          inputFieldName,
+          apolloPath,
+          overwrite,
         }),
       );
       return;
@@ -1618,19 +1979,29 @@ async function runEnrichCommand(ctx: CrmCliContext): Promise<void> {
       const fieldName = getFlag(ctx.args, "--field");
       const missingOnly = !hasFlag(ctx.args, "--all");
       const provider = getFlag(ctx.args, "--provider");
+      const inputFieldName = getFlag(ctx.args, "--input-field");
+      const category = parseCategoryFlag(getFlag(ctx.args, "--category"));
+      const apolloPath = getFlag(ctx.args, "--apollo-path");
+      const overwrite = hasFlag(ctx.args, "--overwrite");
+      const limit = parsePositiveInt("--limit", getFlag(ctx.args, "--limit"));
       assertNoUnknownFlags(ctx.args, "crm enrich object");
       if (!fieldName) {
         throw new CrmCliError(
-          "dench crm enrich object <name> --field <field> [--provider ...] [--all]",
+          "dench crm enrich object <name> --field <field> [--input-field <field>] [--category people|company] [--apollo-path <path>] [--limit N] [--provider ...] [--all] [--overwrite]",
         );
       }
       out(
         ctx,
-        await callMutation(ctx, api.enrich.requestObjectEnrichment, {
+        await enrichObjectThroughGateway(ctx, {
           objectName,
           fieldName,
           provider,
+          category,
+          inputFieldName,
+          apolloPath,
           missingOnly,
+          overwrite,
+          limit,
         }),
       );
       return;
@@ -1758,14 +2129,14 @@ SQL escape hatch (subset; flat SELECTs only):
 People + companies shortcuts:
   dench crm people search '<query>'
   dench crm people upsert --data '{"Email Address":"jane@example.com",...}'   (alias: --fields)
-  dench crm people enrich <entryId> [--provider apollo]
+  dench crm people enrich <entryId> [--field 'LinkedIn URL'] [--input-field 'Email Address']
   dench crm companies search '<query>'
   dench crm companies upsert --domain acme.com [--name Acme]
-  dench crm companies enrich <entryId>
+  dench crm companies enrich <entryId> [--field 'Company Name'] [--input-field Domain]
 
 Cell / row / object enrichment:
-  dench crm enrich cell <object> <entryId> <field> [--provider ...]
-  dench crm enrich object <object> --field <field> [--provider ...] [--all]
+  dench crm enrich cell <object> <entryId> <field> [--input-field <field>] [--category people|company] [--apollo-path <path>] [--overwrite]
+  dench crm enrich object <object> --field <field> [--input-field <field>] [--category people|company] [--apollo-path <path>] [--limit N] [--all] [--overwrite]
 
 Reports (chart-ready JSON):
   dench crm reports generate '<name>' --object <object> --type pie|bar|line|table --group-by <field> [--metric count|sum --metric-field <field>]

package/dench

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
 
+import { loadDevEnv } from "./lib/load-dev-env.mjs";
+
+loadDevEnv(import.meta.url);
+
 const entrypoint = new URL("./dench.ts", import.meta.url).href;
 
 if (process.versions.bun) {

package/dench.mjs

@@ -1,5 +1,9 @@
 #!/usr/bin/env node
 
+import { loadDevEnv } from "./lib/load-dev-env.mjs";
+
+loadDevEnv(import.meta.url);
+
 const entrypoint = new URL("./dench.ts", import.meta.url).href;
 
 if (process.versions.bun) {

package/dench.ts

@@ -1809,6 +1809,30 @@ async function getRuntime() {
       });
     }
 
+    // Sandbox session-mode path: workflow minting provisions a real
+    // dch_agent_* token at sandbox-create time. Prefer it over apiKey so
+    // agentWorkspace.* commands (Composio tools) work inside sandboxes.
+    const sandboxAgentToken = process.env.DENCH_AGENT_SESSION_TOKEN?.trim();
+    const sandboxConvexUrl = resolveApiKeyConvexUrl();
+    if (sandboxAgentToken && sandboxConvexUrl) {
+      const orgId = process.env.DENCH_ORG_ID?.trim();
+      const orgSlug = process.env.DENCH_ORG_SLUG?.trim();
+      const apiHost =
+        process.env.DENCH_API_URL?.trim() ||
+        process.env.DENCH_INTERNAL_BASE?.trim() ||
+        host;
+      return {
+        mode: "session" as const,
+        host: apiHost,
+        client: new ConvexHttpClient(sandboxConvexUrl),
+        sessionToken: sandboxAgentToken,
+        organization:
+          orgId && orgSlug
+            ? { id: orgId, name: orgSlug, slug: orgSlug }
+            : undefined,
+      };
+    }
+
     // Sandbox / automation path: the unified Dench API key + Convex URL
     // baked into sandbox envVars (see
     // src/lib/secrets/sandbox-tokens.ts) is enough to drive every

package/fs-daemon.ts

@@ -108,6 +108,7 @@ function shouldIgnore(relPath: string): boolean {
   const parts = relPath.split("/").filter(Boolean);
   const blockedDirs = new Set([
     ".chrome-profile",
+    ".dench",
     ".git",
     ".next",
     ".vercel",

package/home-sync

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const entrypoint = new URL("./home-sync.ts", import.meta.url).href;
+
+if (process.versions.bun) {
+  await import(entrypoint);
+} else {
+  const { tsImport } = await import("tsx/esm/api");
+  await tsImport(entrypoint, import.meta.url);
+}