@dench.com/cli 0.3.7 → 0.4.0

package/README.md

@@ -195,11 +195,14 @@ dench crm entries list people
 
 Auth precedence:
 
-1. `--dev` flag → use the dev workspace env (`NEXT_PUBLIC_CONVEX_URL`,
+1. Explicit `--dev` flag → use the dev workspace env (`NEXT_PUBLIC_CONVEX_URL`,
    `DENCH_WORKSPACE`, `DENCH_DEV_AGENT_KEY`).
 2. A locally-stored `dench login` session for the current host.
 3. `DENCH_API_KEY` + `CONVEX_URL` (sandbox / automation path).
-4. `--dev`-style env vars (without the flag).
+
+Plain terminal usage does not silently fall back to dev env vars. Without
+`--dev`, a saved session, or `DENCH_API_KEY` + `CONVEX_URL`, live commands
+return `login_required`.
 
 Commands that need to impersonate a specific agent (`dench memory`,
 `dench task`, `dench claim`, `dench log`, `dench approval request`,

package/agent.ts

@@ -34,6 +34,20 @@ type CliCtx = {
   convex: ConvexHttpClient;
   args: string[];
   jsonOutput: boolean;
+  /**
+   * Bearer token forwarded by the dispatcher in `cli/dench.ts`. Either a
+   * `dch_agent_*` agent session minted by `dench login` or a unified
+   * Dench API key (`DENCH_API_KEY`) when the CLI is running inside a
+   * sandbox. Used by `runAwait` to authenticate against
+   * `runs:getChildRunStatusForCli`.
+   */
+  sessionToken?: string;
+  /**
+   * Convex `runs._id` of the caller's own run, when authenticated via
+   * an API key (sandbox path). Required by `getChildRunStatusForCli`
+   * to scope the API key's reach to a specific organization.
+   */
+  callerRunId?: string;
 };
 
 // Args helpers moved to cli/lib/cli-args.ts; we adapt shift to throw
@@ -137,10 +151,18 @@ async function postJson(
 export async function runAgentCommand(opts: {
   convex: ConvexHttpClient;
   args: string[];
+  sessionToken?: string;
+  callerRunId?: string;
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
-  const ctx: CliCtx = { convex: opts.convex, args, jsonOutput };
+  const ctx: CliCtx = {
+    convex: opts.convex,
+    args,
+    jsonOutput,
+    sessionToken: opts.sessionToken,
+    callerRunId: opts.callerRunId,
+  };
   const subcommand = args.shift();
   if (!subcommand || subcommand === "help" || subcommand === "--help") {
     agentHelp();
@@ -243,27 +265,81 @@ async function runAwait(ctx: CliCtx): Promise<void> {
       "dench agent await requires --hook <token> or --children <csv>",
     );
   }
-  // Polling fallback: subscribe to runs via Convex realtime would be the
-  // proper implementation; for v1 we poll status fields every 2s.
-  const childIds = childIdsCsv.split(",").map((id) => id.trim()).filter(Boolean);
-  const completed: Record<string, string> = {};
+  if (!ctx.sessionToken) {
+    throw new AgentCliError(
+      "dench agent await --children needs an authenticated session " +
+        "(run `dench login`, or set DENCH_API_KEY in a sandbox)",
+    );
+  }
+
+  const childIds = childIdsCsv
+    .split(",")
+    .map((id) => id.trim())
+    .filter(Boolean);
+  if (childIds.length === 0) {
+    throw new AgentCliError("--children requires at least one run id");
+  }
   const start = Date.now();
   const timeoutMs = parseInt(
     getFlag(ctx.args, "--timeout-ms") ?? "3600000",
     10,
   );
+  const intervalMs = parseInt(
+    getFlag(ctx.args, "--interval-ms") ?? "2000",
+    10,
+  );
+
+  type ChildSnapshot = {
+    runId: string;
+    status: string;
+    summary: string | null;
+    threadId: string | null;
+    terminal: boolean;
+  };
+  const getStatus = makeFunctionReference<"query">(
+    "functions/runs:getChildRunStatusForCli",
+  );
+
+  // Poll each child's status until it reaches a terminal state. The
+  // server uses sessionToken auth (mirrors `dench chat list`) so this
+  // works both for `dch_agent_*` sessions (local dev) and for unified
+  // `DENCH_API_KEY`s (sandbox, must include `--caller-run-id`).
+  const completed: Record<string, ChildSnapshot> = {};
   while (Object.keys(completed).length < childIds.length) {
     if (Date.now() - start > timeoutMs) {
-      throw new AgentCliError("dench agent await timed out");
+      throw new AgentCliError(
+        `dench agent await timed out after ${timeoutMs}ms with ${
+          Object.keys(completed).length
+        }/${childIds.length} children completed`,
+      );
     }
     for (const childId of childIds) {
       if (completed[childId]) continue;
-      // Reading status requires a query; for v1 use a tight loop on the
-      // public runs.getRun. (Wired in P5 once DenchClient lands.)
-      completed[childId] = "pending";
+      try {
+        const snap = (await ctx.convex.query(getStatus, {
+          sessionToken: ctx.sessionToken,
+          runId: ctx.callerRunId ?? undefined,
+          childRunId: childId as never,
+        })) as ChildSnapshot | null;
+        if (snap?.terminal) {
+          completed[childId] = snap;
+        }
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        // Treat "not found" / access errors as terminal-with-error so
+        // we don't poll forever on a typo'd id.
+        completed[childId] = {
+          runId: childId,
+          status: "error",
+          summary: msg,
+          threadId: null,
+          terminal: true,
+        };
+      }
+    }
+    if (Object.keys(completed).length < childIds.length) {
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
     }
-    await new Promise((resolve) => setTimeout(resolve, 2000));
-    break; // v1 polling stub — placeholder
   }
   out(ctx, { children: completed });
 }
@@ -367,12 +443,18 @@ function agentHelp(): void {
 Spawn a chat-turn workflow (same as the web UI's chat panel):
   dench agent new "<prompt>" [--model <m>] [--file-context <path>] [--visibility private|shared] [--title T] [--yolo] [--follow] [--json]
   dench agent send <thread-id> "<message>" [--model <m>] [--yolo] [--follow] [--json]
-  These are aliases for \`dench chat new\` / \`dench chat send\`.
+  dench agent follow <thread-id> [--json]
+  These are aliases for \`dench chat new\` / \`dench chat send\` / \`dench chat follow\`.
+  Use \`follow\` to tail the live stream of an existing thread (e.g.
+  a subagent spawned by \`spawn_agent\`) without sending a new message.
 
 Subagents (autonomous Long Sessions, NOT chat threads):
   dench agent spawn '<goal>' [--parent-run-id <id>] [--sandbox own|share_parent] [--time-budget-ms N]
   dench agent await --hook <token>
-  dench agent await --children id1,id2,id3 [--timeout-ms N]
+  dench agent await --children id1,id2,id3 [--timeout-ms N] [--interval-ms N]
+                                            (polls runs:getChildRunStatusForCli
+                                             with the active session token until
+                                             every child is terminal)
 
 Peer messaging:
   dench agent message <toRunId> '<text...>' [--from-run-id <id>]

package/chat-spawn.ts

@@ -87,21 +87,47 @@ function buildSpawnUrl(host: string): string {
   return `${host.replace(/\/+$/, "")}/api/chat/cli`;
 }
 
-function buildStreamUrl(host: string, runId: string): string {
+function buildStreamUrlByRunId(host: string, runId: string): string {
   return `${host.replace(/\/+$/, "")}/api/chat/${encodeURIComponent(runId)}/stream`;
 }
 
+function buildStreamUrlByThreadId(host: string, threadId: string): string {
+  return `${host.replace(/\/+$/, "")}/api/chat/stream?sessionId=${encodeURIComponent(threadId)}`;
+}
+
 /**
  * Subscribe to the durable chat stream and pretty-print useful chunks
  * until the stream closes. Mirrors the chunk types the chat panel
  * cares about (text deltas, reasoning, tool input/output, finish).
+ *
+ * Resolves the stream URL from EITHER:
+ *   - `runId` (Workflow SDK run id, returned in `x-workflow-run-id`
+ *     by `POST /api/chat/cli`), via `/api/chat/[runId]/stream`, OR
+ *   - `threadId` (Convex `chatThreads._id`), via
+ *     `/api/chat/stream?sessionId=...` which resolves the active run
+ *     by following `chatThreads.activeRunId → runs.workflowRunId`.
+ *
+ * The thread-id path is what `dench chat follow <threadId>` uses, so
+ * we can tail any live thread (including a subagent created by
+ * `spawn_agent`) without needing to know its workflow run id ahead of
+ * time.
  */
 async function followStream(args: {
   host: string;
   bearerToken: string;
-  runId: string;
+  runId?: string;
+  threadId?: string;
 }): Promise<void> {
-  const url = buildStreamUrl(args.host, args.runId);
+  const url = args.runId
+    ? buildStreamUrlByRunId(args.host, args.runId)
+    : args.threadId
+      ? buildStreamUrlByThreadId(args.host, args.threadId)
+      : null;
+  if (!url) {
+    throw new ChatSpawnError(
+      "followStream requires either { runId } or { threadId }",
+    );
+  }
   const response = await fetch(url, {
     method: "GET",
     headers: {
@@ -342,6 +368,37 @@ async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
   }
 }
 
+/**
+ * `dench chat follow <threadId>` — tail the live stream of an
+ * existing chat thread by Convex thread id.
+ *
+ * Useful for watching a subagent (a child thread spawned by a parent
+ * via `spawn_agent`) live, or for resuming the stream of any chat
+ * thread that's currently in flight. Resolves the active workflow run
+ * server-side via `chatThreads.activeRunId → runs.workflowRunId`, so
+ * the caller doesn't need to know any workflow ids.
+ *
+ * Exits when the stream closes (workflow finishes) or when the user
+ * hits Ctrl-C.
+ */
+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]",
+    );
+  }
+  if (!ctx.jsonOutput) {
+    console.error(`--- following stream for thread ${threadId} ---`);
+  }
+  await followStream({
+    host: ctx.runtime.host,
+    bearerToken: ctx.runtime.bearerToken,
+    threadId,
+  });
+}
+
 /**
  * Public entry point invoked by the chat dispatcher in cli/dench.ts
  * (and the agent dispatcher when the user runs `dench agent new` /
@@ -351,7 +408,7 @@ async function runChatSend(ctx: ChatSpawnContext): Promise<void> {
 export async function runChatSpawnCommand(opts: {
   runtime: RuntimeBundle;
   args: string[];
-  subcommand: "new" | "send";
+  subcommand: "new" | "send" | "follow";
 }): Promise<void> {
   const args = [...opts.args];
   const jsonOutput = hasFlag(args, "--json");
@@ -364,6 +421,10 @@ export async function runChatSpawnCommand(opts: {
     await runChatNew(ctx);
     return;
   }
+  if (opts.subcommand === "follow") {
+    await runChatFollow(ctx);
+    return;
+  }
   await runChatSend(ctx);
 }
 

package/chat.ts

@@ -1,11 +1,12 @@
 /**
- * `dench chat <subcommand>` — CLI surface for browsing past chat threads
- * in the user's workspace.
+ * `dench chat <subcommand>` — CLI surface for browsing and managing
+ * past chat threads in the user's workspace.
  *
  * Mirrors the `dench crm` pattern: a thin command dispatcher on top of
- * Convex public queries (`functions/chat:listPastChats`,
- * `searchPastChats`, `readPastChat`) which themselves enforce the
- * "own + shared in this org" visibility rule.
+ * Convex public queries/mutations (`functions/chat:listPastChats`,
+ * `searchPastChats`, `readPastChat`, `renameThreads`, `deleteThreads`)
+ * which themselves enforce the "own + shared in this org" visibility
+ * rule (`requireThreadAccess`).
  *
  * Auth: every call forwards a single bearer token via `sessionToken`
  * (either a `dch_agent_*` agent session minted by `dench login` or a
@@ -16,9 +17,13 @@
  * inside a sandbox without extra flags.
  *
  * Subcommands:
- *   chat list   [--query <substr>] [--limit N] [--include-archived]
- *   chat search <query>            [--limit N] [--include-current]
- *   chat read   <thread-id>        [--limit N]
+ *   chat list    [--query <substr>] [--limit N] [--include-archived]
+ *   chat search  <query>            [--limit N] [--include-current]
+ *   chat read    <thread-id>        [--limit N]
+ *   chat rename  <thread-id> <new-title>           # single rename
+ *   chat rename  --from-stdin                       # batch via JSON {items:[...]}
+ *   chat delete  <thread-id> [<thread-id>...]      # 1–25 ids, --yes to skip prompt
+ *   chat delete  --ids id1,id2,id3                  # comma-separated form
  */
 import type { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
@@ -67,6 +72,12 @@ const api = {
   readPastChat: makeFunctionReference<"query">(
     "functions/chat:readPastChat",
   ),
+  renameThreads: makeFunctionReference<"mutation">(
+    "functions/chat:renameThreads",
+  ),
+  deleteThreads: makeFunctionReference<"mutation">(
+    "functions/chat:deleteThreads",
+  ),
 };
 
 function commonArgs(ctx: ChatCliContext) {
@@ -84,6 +95,14 @@ async function callQuery(
   return ctx.convex.query(fn, { ...args, ...commonArgs(ctx) } as never);
 }
 
+async function callMutation(
+  ctx: ChatCliContext,
+  fn: Parameters<ConvexHttpClient["mutation"]>[0],
+  args: Record<string, unknown> = {},
+): Promise<unknown> {
+  return ctx.convex.mutation(fn, { ...args, ...commonArgs(ctx) } as never);
+}
+
 function out(ctx: ChatCliContext, value: unknown): void {
   if (ctx.jsonOutput) {
     console.log(JSON.stringify(value, null, 2));
@@ -108,10 +127,28 @@ Full-text search across past chat messages (own + shared):
 Read messages from a specific past chat thread:
   dench chat read <thread-id> [--limit N] [--json]
 
+Rename one or more past chat threads (own + shared):
+  dench chat rename <thread-id> <new-title> [--json]
+  dench chat rename --from-stdin [--json]
+    Reads JSON {"items":[{"threadId":"...","title":"..."}, ...]} from stdin.
+    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]
+    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.
+
 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]
-  Aliased as: dench agent new / dench agent send.
+  dench chat follow <thread-id> [--json]
+  dench chat tree [<root-thread-id>] [--limit N] [--json]
+  Aliased as: dench agent new / dench agent send / dench agent follow.
+  Use \`follow\` to tail any live thread by id (e.g. a subagent
+  spawned by another chat). Use \`tree\` to print the parent-child
+  thread hierarchy from a root thread.
 
 Approval policy:
   Without --yolo the workflow uses the workspace policy from
@@ -156,6 +193,13 @@ export async function runChatCommand(opts: {
       return await runChatSearchCommand(ctx);
     case "read":
       return await runChatReadCommand(ctx);
+    case "tree":
+      return await runChatTreeCommand(ctx);
+    case "rename":
+      return await runChatRenameCommand(ctx);
+    case "delete":
+    case "rm":
+      return await runChatDeleteCommand(ctx);
     default:
       throw new ChatCliError(`Unknown chat subcommand: ${subcommand}`);
   }
@@ -214,3 +258,299 @@ async function runChatReadCommand(ctx: ChatCliContext): Promise<void> {
     }),
   );
 }
+
+async function readStdin(): Promise<string> {
+  if (process.stdin.isTTY) {
+    throw new ChatCliError(
+      "--from-stdin requires JSON piped on stdin (got TTY).",
+    );
+  }
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin as AsyncIterable<Buffer>) {
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function runChatRenameCommand(ctx: ChatCliContext): Promise<void> {
+  const fromStdin = hasFlag(ctx.args, "--from-stdin");
+  let items: Array<{ threadId: string; title: string }>;
+  if (fromStdin) {
+    const raw = (await readStdin()).trim();
+    if (!raw) {
+      throw new ChatCliError(
+        'Empty --from-stdin payload; expected {"items":[...]}.',
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      throw new ChatCliError(
+        `Invalid JSON on stdin: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      !Array.isArray((parsed as { items?: unknown }).items)
+    ) {
+      throw new ChatCliError(
+        'Stdin JSON must be {"items":[{"threadId":"...","title":"..."}]}.',
+      );
+    }
+    const rawItems = (parsed as { items: unknown[] }).items;
+    items = rawItems.map((entry, index) => {
+      if (
+        !entry ||
+        typeof entry !== "object" ||
+        typeof (entry as { threadId?: unknown }).threadId !== "string" ||
+        typeof (entry as { title?: unknown }).title !== "string"
+      ) {
+        throw new ChatCliError(
+          `items[${index}] must be { threadId: string, title: string }.`,
+        );
+      }
+      const item = entry as { threadId: string; title: string };
+      if (!item.threadId.trim()) {
+        throw new ChatCliError(`items[${index}].threadId is empty.`);
+      }
+      if (!item.title.trim()) {
+        throw new ChatCliError(`items[${index}].title is empty.`);
+      }
+      return { threadId: item.threadId.trim(), title: item.title };
+    });
+  } else {
+    const threadId = shift(ctx.args, "thread id").trim();
+    const titleParts: string[] = [];
+    while (ctx.args.length > 0) {
+      const next = ctx.args.shift();
+      if (next === undefined) break;
+      if (next.startsWith("--")) {
+        ctx.args.unshift(next);
+        break;
+      }
+      titleParts.push(next);
+    }
+    const title = titleParts.join(" ").trim();
+    if (!title) {
+      throw new ChatCliError(
+        "Usage: dench chat rename <thread-id> <new-title>",
+      );
+    }
+    items = [{ threadId, title }];
+  }
+  if (items.length === 0) {
+    throw new ChatCliError("Nothing to rename.");
+  }
+  if (items.length > 50) {
+    throw new ChatCliError(
+      `Too many items (${items.length}); the server caps each call at 50.`,
+    );
+  }
+  out(ctx, await callMutation(ctx, api.renameThreads, { items }));
+}
+
+async function promptYesNo(question: string): Promise<boolean> {
+  if (!process.stdin.isTTY) return false;
+  process.stdout.write(`${question} [y/N] `);
+  return new Promise<boolean>((resolve) => {
+    const onData = (chunk: Buffer) => {
+      const answer = chunk.toString("utf8").trim().toLowerCase();
+      cleanup();
+      resolve(answer === "y" || answer === "yes");
+    };
+    const cleanup = () => {
+      process.stdin.off("data", onData);
+      try {
+        process.stdin.pause();
+      } catch {
+        // ignore: stdin may already be closed.
+      }
+    };
+    process.stdin.resume();
+    process.stdin.once("data", onData);
+  });
+}
+
+async function runChatDeleteCommand(ctx: ChatCliContext): Promise<void> {
+  const idsFlag = getFlag(ctx.args, "--ids");
+  const skipConfirm = hasFlag(ctx.args, "--yes") || hasFlag(ctx.args, "-y");
+  const collected: string[] = [];
+  if (idsFlag) {
+    for (const part of idsFlag.split(",")) {
+      const trimmed = part.trim();
+      if (trimmed) collected.push(trimmed);
+    }
+  }
+  while (ctx.args.length > 0) {
+    const next = ctx.args.shift();
+    if (next === undefined) break;
+    if (next.startsWith("--")) {
+      ctx.args.unshift(next);
+      break;
+    }
+    if (next.trim()) collected.push(next.trim());
+  }
+  const seen = new Set<string>();
+  const threadIds = collected.filter((id) => {
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
+  if (threadIds.length === 0) {
+    throw new ChatCliError(
+      "Usage: dench chat delete <thread-id> [<thread-id>...]  (or --ids id1,id2,...)",
+    );
+  }
+  if (threadIds.length > 25) {
+    throw new ChatCliError(
+      `Too many thread ids (${threadIds.length}); the server caps each call at 25. Run multiple invocations.`,
+    );
+  }
+  if (!skipConfirm) {
+    if (!process.stdin.isTTY) {
+      throw new ChatCliError(
+        "Refusing to delete without --yes in non-interactive mode (no TTY).",
+      );
+    }
+    const ok = await promptYesNo(
+      `PERMANENTLY delete ${threadIds.length} chat${
+        threadIds.length === 1 ? "" : "s"
+      } and all their messages?`,
+    );
+    if (!ok) {
+      console.error("Aborted.");
+      return;
+    }
+  }
+  out(ctx, await callMutation(ctx, api.deleteThreads, { threadIds }));
+}
+
+/**
+ * `dench chat tree [<root-thread-id>] [--limit N] [--json]` — print the
+ * parent-child chat thread hierarchy rooted at the given thread (or
+ * roots = top-level chats if no id is passed).
+ *
+ * Uses `listPastChats` (which already includes nested threads in its
+ * results — `topLevelOnly` is a `listThreads`-only knob) and groups
+ * client-side by `parentThreadId`. With `--json`, prints the raw flat
+ * array; otherwise prints an indented tree with status + a short
+ * summary excerpt for each row.
+ */
+async function runChatTreeCommand(ctx: ChatCliContext): Promise<void> {
+  // Strip flag values from positionals so e.g. `tree --limit 30` doesn't
+  // misinterpret "30" as the rootThreadId. We treat "--key value" as a
+  // pair iff value doesn't itself start with "--".
+  const positionals: string[] = [];
+  for (let i = 0; i < ctx.args.length; i++) {
+    const arg = ctx.args[i];
+    if (arg.startsWith("--")) {
+      const next = ctx.args[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        i += 1; // skip the flag value
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+  const rootThreadId = positionals[0]?.trim() || undefined;
+  const limit = parseLimit(getFlag(ctx.args, "--limit")) ?? 200;
+
+  const flat = (await callQuery(ctx, api.listPastChats, {
+    limit,
+    includeArchived: false,
+  })) as Array<{
+    threadId: string;
+    title: string;
+    status: string;
+    parentThreadId: string | null;
+    nestingDepth: number | null;
+    summary: string | null;
+    lastMessageAt: number;
+    createdAt: number;
+    activeRunId: string | null;
+  }>;
+
+  if (ctx.jsonOutput) {
+    out(ctx, flat);
+    return;
+  }
+
+  // Group by parent. Top-level rows = either no parent, or parent
+  // outside the loaded set (so we don't silently swallow children
+  // whose parent fell off the limit window).
+  const ids = new Set(flat.map((t) => t.threadId));
+  const childrenByParent = new Map<string, typeof flat>();
+  const roots: typeof flat = [];
+  for (const thread of flat) {
+    if (thread.parentThreadId && ids.has(thread.parentThreadId)) {
+      let list = childrenByParent.get(thread.parentThreadId);
+      if (!list) {
+        list = [];
+        childrenByParent.set(thread.parentThreadId, list);
+      }
+      list.push(thread);
+      continue;
+    }
+    if (rootThreadId) {
+      if (thread.threadId === rootThreadId) roots.push(thread);
+    } else {
+      roots.push(thread);
+    }
+  }
+  // When the user passed an explicit `rootThreadId` but it didn't
+  // appear in the loaded set (e.g. it sits beyond `--limit`), pull
+  // it on its own so we still surface it as the single root.
+  if (rootThreadId && roots.length === 0) {
+    const explicit = flat.find((t) => t.threadId === rootThreadId);
+    if (explicit) roots.push(explicit);
+  }
+  // Sort children oldest-first within each parent (spawn order),
+  // roots newest-first (most recent root at the top).
+  for (const list of childrenByParent.values()) {
+    list.sort((a, b) => (a.createdAt || a.lastMessageAt) - (b.createdAt || b.lastMessageAt));
+  }
+  roots.sort((a, b) => b.lastMessageAt - a.lastMessageAt);
+
+  if (roots.length === 0) {
+    if (rootThreadId) {
+      console.error(
+        `No thread found with id ${rootThreadId} (or it's outside the limit ` +
+          `${limit} window — increase --limit).`,
+      );
+    } else {
+      console.error("No chat threads in this workspace yet.");
+    }
+    return;
+  }
+
+  const stripe = (s: string, n: number) =>
+    s.length > n ? `${s.slice(0, n - 1)}…` : s;
+  const print = (thread: (typeof flat)[number], depth: number): void => {
+    const indent = "  ".repeat(depth);
+    const branch = depth > 0 ? "└─ " : "";
+    const status =
+      thread.status === "streaming"
+        ? "▸ running"
+        : thread.status === "error"
+          ? "✗ error"
+          : thread.summary
+            ? "✓ done"
+            : "·";
+    process.stdout.write(
+      `${indent}${branch}[${status}] ${stripe(thread.title || "Untitled", 60)}  ` +
+        `(${thread.threadId})\n`,
+    );
+    if (thread.summary) {
+      process.stdout.write(
+        `${indent}${depth > 0 ? "   " : ""}${stripe(thread.summary.replace(/\s+/g, " "), 80)}\n`,
+      );
+    }
+    const direct = childrenByParent.get(thread.threadId) ?? [];
+    for (const child of direct) print(child, depth + 1);
+  };
+  for (const root of roots) print(root, 0);
+}

package/cron.ts

@@ -5,10 +5,12 @@
  * Each cron is a row in the Convex `triggers` table that, when due,
  * spawns a fresh chat thread (the `target: "chat_turn"` path — new
  * default) running in YOLO mode and seeded with the cron's prompt as
- * the first user message. The Vercel cron dispatcher (`/api/cron/dispatch`,
- * scheduled via `vercel.json` at every minute) walks the
- * `by_enabled_nextFireAt` index, claims due rows, and fires the
- * workflow.
+ * the first user message. Scheduling is owned by the
+ * `@convex-dev/crons` component: each create/update/enable mutation
+ * registers a component cron under name=triggerId; the component fires
+ * `internal.functions.triggersNode.fireDenchTrigger` at the precise
+ * scheduled time, which then POSTs to `/api/runs/spawn-{chat,child}`
+ * to start the workflow.
  *
  * Auth: prefers the unified Dench API key from `DENCH_API_KEY`
  * (sandbox envVar baked at create time). Falls back to `dench login`
@@ -504,6 +506,8 @@ async function runHistory(ctx: CronCliContext): Promise<void> {
 
 function cronHelp(): void {
   console.log(`Usage: dench cron <subcommand>
+       dench routine <subcommand>     (alias)
+       dench routines <subcommand>    (alias)
 
 Browse:
   dench cron list [--enabled-only] [--json]

package/dench.ts

@@ -327,6 +327,41 @@ function throwIfCliError(value: unknown) {
   }
 }
 
+function normalizeCliError(error: unknown): CliError {
+  if (error instanceof CliError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("Invalid dev agent key")) {
+    return new CliError("Invalid dev agent key", {
+      code: "invalid_dev_agent_key",
+      nextActions: [
+        "Check that DENCH_DEV_AGENT_KEY in your shell matches the Convex deployment env.",
+        "Use --dev only for a local/dev Convex deployment configured with that key.",
+        "For normal terminal usage, run dench login or set DENCH_API_KEY + CONVEX_URL.",
+      ],
+    });
+  }
+  if (message.includes("Dev CRM access is disabled in production")) {
+    return new CliError("Dev CRM access is disabled in production", {
+      code: "dev_access_disabled",
+      nextActions: [
+        "Remove --dev and run dench login for terminal access.",
+        "Or use DENCH_API_KEY + CONVEX_URL for sandbox/automation access.",
+      ],
+    });
+  }
+  if (message.includes("Invalid Dench API key")) {
+    return new CliError("Invalid Dench API key", {
+      code: "invalid_api_key",
+      nextActions: [
+        "Check DENCH_API_KEY and CONVEX_URL point to the same organization/deployment.",
+        "Unset DENCH_API_KEY to use a saved dench login session instead.",
+        "Or run dench login to create a new terminal session.",
+      ],
+    });
+  }
+  return new CliError(message);
+}
+
 function parseJsonObjectOption(name: string) {
   const raw = option(name);
   if (!raw) return {};
@@ -457,12 +492,20 @@ Past chat threads (own + shared in this workspace):
   dench chat list [--query <substr>] [--limit N] [--include-archived] [--json]
   dench chat search "<query>" [--limit N] [--include-current] [--json]
   dench chat read <thread-id> [--limit N] [--json]
+  dench chat rename <thread-id> <new-title> [--json]
+  dench chat rename --from-stdin [--json]            (batch via JSON {items:[...]})
+  dench chat delete <thread-id> [<thread-id>...] [--yes] [--json]
+  dench chat delete --ids id1,id2 [--yes] [--json]   (PERMANENTLY deletes threads)
 
 Spawn a new chat-turn workflow (same 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]
-  dench agent new ...    (alias for dench chat new)
-  dench agent send ...   (alias for dench chat send)
+  dench chat follow <thread-id> [--json]            (tail a live thread by id)
+  dench chat tree [<root-thread-id>] [--limit N] [--json]
+                                                    (parent-child thread tree)
+  dench agent new ...     (alias for dench chat new)
+  dench agent send ...    (alias for dench chat send)
+  dench agent follow ...  (alias for dench chat follow)
 
   Help: dench chat help
 
@@ -495,6 +538,20 @@ Subagents (Daytona-native rewrite):
 
   dench --version
 
+Self-updating agent harness (OpenClaw parity):
+  dench identity show | edit                    IDENTITY.md (org-wide)
+  dench organisation show | edit                ORGANISATION.md
+  dench user show | edit                        USER.md (per-member)
+  dench tools show | edit                       TOOLS.md notes section
+  dench mem show | append "<text>" | set        MEMORY.md aggregate
+  dench heartbeat status | enable | disable
+                  | interval <30m|1h|…> | instructions
+  dench bootstrap status | complete | reopen | template
+  dench model default <id|clear>
+  dench model thread <threadId> <id|clear>
+  dench daily today | show <YYYY-MM-DD>
+  Help: dench identity help
+
 External tools:
   dench apps is an alias for dench tool status -- it lists connected apps.
   dench tool with no subcommand prints tool help.
@@ -1781,10 +1838,12 @@ async function getRuntime() {
             : undefined,
       };
     }
+
+    throw loginRequiredError();
   }
 
   if (!hasDevEnv()) {
-    throw hasFlag("--dev") ? missingDevEnvError() : loginRequiredError();
+    throw missingDevEnvError();
   }
 
   return {
@@ -1799,6 +1858,22 @@ async function getRuntime() {
 
 type Runtime = Awaited<ReturnType<typeof getRuntime>>;
 
+function stripRuntimeFlags(args: string[]) {
+  const booleanFlags = new Set(["--dev", "--prod", "--staging"]);
+  const valueFlags = new Set(["--convex-url", "--host"]);
+  const stripped: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (booleanFlags.has(arg)) continue;
+    if (valueFlags.has(arg)) {
+      i++;
+      continue;
+    }
+    stripped.push(arg);
+  }
+  return stripped;
+}
+
 /**
  * `session` mode is required for `agentWorkspace.*` calls because they
  * gate on `validateAgentSession` server-side, which only accepts the
@@ -1837,6 +1912,13 @@ function requireAuthenticatedRuntime(
   throw loginRequiredError(command);
 }
 
+function encodeDevCrmSessionToken(args: {
+  workspaceSlug: string;
+  devKey: string;
+}) {
+  return `dch_dev_${encodeURIComponent(args.workspaceSlug)}:${encodeURIComponent(args.devKey)}`;
+}
+
 function agentSessionRequiredError(command: string) {
   return new CliError(
     `${command} requires an agent session — DENCH_API_KEY is org-scoped and cannot impersonate a specific agent`,
@@ -3458,7 +3540,7 @@ async function main() {
   }
 
   if (command === "crm") {
-    const subArgs = args.slice(args.indexOf("crm") + 1);
+    const subArgs = stripRuntimeFlags(args.slice(args.indexOf("crm") + 1));
     const sub = subArgs[0];
     // Short-circuit help so users don't need a session to read the
     // surface. The crm dispatcher's own help resolves --json + the
@@ -3478,6 +3560,14 @@ async function main() {
     // (`DENCH_API_KEY` baked into sandbox envVars). Server-side
     // `requireCrmAccess` (convex/lib/crm/access.ts) dispatches on the
     // bearer prefix and resolves the org for both.
+    if (runtime.mode === "dev") {
+      await runCrmCommand({
+        convex: runtime.client,
+        args: subArgs,
+        sessionToken: encodeDevCrmSessionToken(runtime.workspaceArgs),
+      });
+      return;
+    }
     const authedRuntime = requireAuthenticatedRuntime(runtime, "dench crm");
     await runCrmCommand({
       convex: authedRuntime.client,
@@ -3534,12 +3624,13 @@ async function main() {
       await runChatCommand({ convex: {} as any, args: subArgs });
       return;
     }
-    // `chat new` / `chat send` spawn a chat-turn workflow via
-    // /api/chat/cli (the same workflow the web UI uses). They need
-    // an HTTP host + bearer token, not a Convex client. The
-    // remaining subcommands (list / search / read) are Convex
-    // queries and keep going through `runChatCommand`.
-    if (sub === "new" || sub === "send") {
+    // `chat new` / `chat send` / `chat follow` use HTTP routes
+    // (/api/chat/cli for spawn, /api/chat/[runId]/stream and
+    // /api/chat/stream for follow) so they need an authenticated host
+    // + bearer token, not a Convex client. The remaining subcommands
+    // (list / search / read / tree) are Convex queries and keep going
+    // through `runChatCommand`.
+    if (sub === "new" || sub === "send" || sub === "follow") {
       const { runChatSpawnCommand } = await import("./chat-spawn");
       const runtime = await getRuntime();
       const authedRuntime = requireAuthenticatedRuntime(
@@ -3583,11 +3674,12 @@ async function main() {
       await runAgentCommand({ convex: {} as any, args: subArgs });
       return;
     }
-    // Aliases: `dench agent new` / `dench agent send` -> the chat-spawn
-    // implementation. Surfaced under `agent` so users who associate
-    // chat threads with the agent surface still find them; the actual
-    // workflow is identical to `dench chat new` / `dench chat send`.
-    if (sub === "new" || sub === "send") {
+    // Aliases: `dench agent new` / `dench agent send` / `dench agent
+    // follow` -> the chat-spawn implementation. Surfaced under
+    // `agent` so users who associate chat threads with the agent
+    // surface still find them; the actual workflow is identical to
+    // `dench chat new` / `dench chat send` / `dench chat follow`.
+    if (sub === "new" || sub === "send" || sub === "follow") {
       const { runChatSpawnCommand } = await import("./chat-spawn");
       const runtime = await getRuntime();
       const authedRuntime = requireAuthenticatedRuntime(
@@ -3609,12 +3701,17 @@ async function main() {
     await runAgentCommand({
       convex: runtime.client,
       args: subArgs,
+      sessionToken: runtime.sessionToken,
+      callerRunId: process.env.DENCH_RUN_ID?.trim() || undefined,
     });
     return;
   }
 
-  if (command === "cron") {
-    const subArgs = args.slice(args.indexOf("cron") + 1);
+  // `dench routine` / `dench routines` are UI-friendly aliases for
+  // `dench cron`. Same dispatch, same auth, same handler — only the
+  // top-level command name differs to match the workspace UI rename.
+  if (command === "cron" || command === "routine" || command === "routines") {
+    const subArgs = args.slice(args.indexOf(command) + 1);
     const sub = subArgs[0];
     // Help is a no-auth path so users can read the surface without a
     // session — mirrors `dench crm help`.
@@ -3633,7 +3730,10 @@ async function main() {
     // bearer prefix and resolves the org for both. The Bearer token
     // must carry `crons:read` (queries) or `crons:write` (mutations)
     // scope, or the wildcard `*`.
-    const authedRuntime = requireAuthenticatedRuntime(runtime, "dench cron");
+    const authedRuntime = requireAuthenticatedRuntime(
+      runtime,
+      `dench ${command}`,
+    );
     await runCronCommand({
       convex: authedRuntime.client,
       args: subArgs,
@@ -3642,6 +3742,85 @@ async function main() {
     return;
   }
 
+  // ── OpenClaw-parity self-update CLI surface ──────────────────────────
+  //
+  // Dispatch all `dench identity / organisation / user / tools / mem /
+  // heartbeat / bootstrap / model / daily` traffic through the shared
+  // agent-config CLI module. Each command requires the same auth shape
+  // as `dench cron` (Bearer DENCH_API_KEY or `dench login` session
+  // token) so server-side `requireCronAccess` accepts both.
+  const AGENT_CONFIG_COMMANDS = new Set([
+    "identity",
+    "organisation",
+    "user",
+    "tools",
+    "mem",
+    "heartbeat",
+    "bootstrap",
+    "model",
+    "daily",
+  ]);
+  if (AGENT_CONFIG_COMMANDS.has(command)) {
+    const subArgs = args.slice(args.indexOf(command) + 1);
+    if (
+      subArgs[0] === "help" ||
+      subArgs.includes("--help") ||
+      subArgs.includes("-h")
+    ) {
+      const { printAgentConfigCliHelp } = await import("./agent-config");
+      printAgentConfigCliHelp();
+      return;
+    }
+    const runtime = await getRuntime();
+    const authedRuntime = requireAuthenticatedRuntime(
+      runtime,
+      `dench ${command}`,
+    );
+    const ctxBase = {
+      convex: authedRuntime.client,
+      args: subArgs,
+      jsonOutput: json,
+      sessionToken: authedRuntime.sessionToken,
+    };
+    const mod = await import("./agent-config");
+    if (command === "identity") {
+      await mod.runIdentityCommand(ctxBase);
+      return;
+    }
+    if (command === "organisation") {
+      await mod.runOrganisationCommand(ctxBase);
+      return;
+    }
+    if (command === "user") {
+      await mod.runUserCommand(ctxBase);
+      return;
+    }
+    if (command === "tools") {
+      await mod.runToolsCommand(ctxBase);
+      return;
+    }
+    if (command === "mem") {
+      await mod.runMemoryAggregateCommand(ctxBase);
+      return;
+    }
+    if (command === "heartbeat") {
+      await mod.runHeartbeatCommand(ctxBase);
+      return;
+    }
+    if (command === "bootstrap") {
+      await mod.runBootstrapCommand(ctxBase);
+      return;
+    }
+    if (command === "model") {
+      await mod.runModelCommand(ctxBase);
+      return;
+    }
+    if (command === "daily") {
+      await mod.runDailyCommand(ctxBase);
+      return;
+    }
+  }
+
   if (command === "login") {
     await login();
     return;
@@ -4237,11 +4416,12 @@ async function main() {
 }
 
 main().catch((error) => {
-  const extra = error instanceof CliError ? error.payload : {};
+  const normalized = normalizeCliError(error);
+  const extra = normalized.payload;
   const payload: JsonRecord = {
     ok: false,
     ...extra,
-    error: error instanceof Error ? error.message : String(error),
+    error: normalized.message,
   };
   if (json) {
     console.error(JSON.stringify(payload, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dench.com/cli",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "Dench agent workspace CLI.",
   "type": "module",
   "bin": {