@dench.com/cli 0.2.0

package/dench.ts

@@ -0,0 +1,3305 @@
+#!/usr/bin/env tsx
+import { Buffer } from "node:buffer";
+import { spawn } from "node:child_process";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir, hostname, userInfo } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { agentKindLabel, normalizeAgentKind } from "./agentKind";
+import {
+  DEFAULT_HOST,
+  isLocalHost,
+  normalizeHost,
+  resolveHostFromArgs,
+  STAGING_HOST,
+} from "./host";
+import { formatApprovalOpenMessage, openUrl } from "./openUrl";
+import {
+  explicitSessionKeyInput,
+  findStoredSessionEntries,
+  listStoredSessionEntries,
+  removeAllStoredSessions,
+  removeStoredSession,
+  resolveConfigHost,
+  resolveSessionScope,
+  type SessionScope,
+  type StoredSessionEntry,
+  selectStoredSession,
+  selectStoredSessionEntry,
+  withCurrentSessionSelection,
+  withSavedSession,
+} from "./session";
+
+type JsonRecord = Record<string, unknown>;
+
+class CliError extends Error {
+  payload: JsonRecord;
+
+  constructor(message: string, payload: JsonRecord = {}) {
+    super(message);
+    this.name = "CliError";
+    this.payload = payload;
+  }
+}
+
+type StoredSession = {
+  host: string;
+  convexUrl: string;
+  sessionToken: string;
+  organization?: { id: string; name: string; slug?: string };
+  agent?: { id: string; name: string; kind: string };
+  sessionScope?: string;
+  sessionScopeLabel?: string;
+  sessionExpiresAt?: number;
+  savedAt: number;
+};
+
+type ConfigFile = {
+  currentHost?: string;
+  currentSessionKey?: string;
+  currentHosts?: Record<string, string>;
+  currentSessionKeys?: Record<string, string>;
+  sessions?: Record<string, StoredSession>;
+};
+
+type WorkspaceOverview = {
+  agents: Array<{ _id: string } & JsonRecord>;
+  projects: JsonRecord[];
+  tasks: JsonRecord[];
+  approvals: Array<{ status?: string } & JsonRecord>;
+  rules: JsonRecord[];
+  recentArtifacts?: JsonRecord[];
+  activeRuns?: JsonRecord[];
+  comments?: JsonRecord[];
+  dependencies?: JsonRecord[];
+  memories?: JsonRecord[];
+};
+
+type AgentStatus = {
+  workspace?: string;
+  workspaceSlug?: string;
+  agent?: { id?: string } & JsonRecord;
+  counts?: JsonRecord;
+  rules?: JsonRecord[];
+  approvals?: Array<{ status?: string; agentId?: string } & JsonRecord>;
+};
+
+const api = {
+  functions: {
+    agentWorkspace: {
+      agentAppendLog: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentAppendLog",
+      ),
+      agentClaimTask: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentClaimTask",
+      ),
+      agentCreateTask: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentCreateTask",
+      ),
+      agentAddTaskComment: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentAddTaskComment",
+      ),
+      agentAddTaskDependency: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentAddTaskDependency",
+      ),
+      agentConvertSuggestionToTask: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentConvertSuggestionToTask",
+      ),
+      agentDecideApproval: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentDecideApproval",
+      ),
+      agentListArtifacts: makeFunctionReference<"query">(
+        "functions/agentWorkspace:agentListArtifacts",
+      ),
+      agentListTasks: makeFunctionReference<"query">(
+        "functions/agentWorkspace:agentListTasks",
+      ),
+      agentRequestApproval: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentRequestApproval",
+      ),
+      agentSaveMemory: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentSaveMemory",
+      ),
+      agentSearchMemory: makeFunctionReference<"query">(
+        "functions/agentWorkspace:agentSearchMemory",
+      ),
+      agentStatus: makeFunctionReference<"query">(
+        "functions/agentWorkspace:agentStatus",
+      ),
+      getAgentBillingStatus: makeFunctionReference<"query">(
+        "functions/agentWorkspace:getAgentBillingStatus",
+      ),
+      agentUpdateTaskStatus: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:agentUpdateTaskStatus",
+      ),
+      createAgentLoginRequest: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:createAgentLoginRequest",
+      ),
+      devAppendLog: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:devAppendLog",
+      ),
+      devClaimTask: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:devClaimTask",
+      ),
+      devCreateProject: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:devCreateProject",
+      ),
+      devCreateTask: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:devCreateTask",
+      ),
+      devListWorkspaceOverview: makeFunctionReference<"query">(
+        "functions/agentWorkspace:devListWorkspaceOverview",
+      ),
+      devRegisterAgent: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:devRegisterAgent",
+      ),
+      devRequestApproval: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:devRequestApproval",
+      ),
+      pollAgentLoginRequest: makeFunctionReference<"mutation">(
+        "functions/agentWorkspace:pollAgentLoginRequest",
+      ),
+      whatCanIDoHere: makeFunctionReference<"query">(
+        "functions/agentWorkspace:whatCanIDoHere",
+      ),
+    },
+    agentToolsNode: {
+      agentToolConnect: makeFunctionReference<"action">(
+        "functions/agentToolsNode:agentToolConnect",
+      ),
+      agentToolRun: makeFunctionReference<"action">(
+        "functions/agentToolsNode:agentToolRun",
+      ),
+      agentToolSearch: makeFunctionReference<"action">(
+        "functions/agentToolsNode:agentToolSearch",
+      ),
+      agentToolStatus: makeFunctionReference<"action">(
+        "functions/agentToolsNode:agentToolStatus",
+      ),
+    },
+  },
+};
+const CONFIG_DIR = join(homedir(), ".dench");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const AUTONOMOUS_DEFAULT_API_BASE = "http://localhost:3000";
+const SAFE_LONG_SESSION_CONSTRAINTS = [
+  "do not edit files",
+  "publish",
+  "deploy",
+  "spend money",
+  "send external messages",
+  "access secrets",
+  "or change production data unless the user explicitly approves it",
+];
+const args = process.argv.slice(2);
+const json = args.includes("--json");
+const filteredArgs = args.filter((arg) => arg !== "--json");
+const scopedStatus = args.includes("--mine") || args.includes("--self");
+
+async function cliVersion() {
+  try {
+    const packageJson = JSON.parse(
+      await readFile(new URL("./package.json", import.meta.url), "utf8"),
+    ) as { version?: unknown };
+    return typeof packageJson.version === "string"
+      ? packageJson.version
+      : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function readEnv(name: string) {
+  const value = process.env[name]?.trim();
+  if (!value) {
+    throw new Error(`Missing ${name}`);
+  }
+  return value;
+}
+
+function option(name: string) {
+  const index = filteredArgs.indexOf(name);
+  if (index === -1) return undefined;
+  return filteredArgs[index + 1];
+}
+
+function hasFlag(name: string) {
+  return filteredArgs.includes(name);
+}
+
+const BOOLEAN_FLAGS = new Set([
+  "--all",
+  "--compact",
+  "--dev",
+  "--help",
+  "--mine",
+  "--self",
+  "--staging",
+  "--prod",
+  "--no-open",
+  "--version",
+  "--ask-before-publishing",
+  "--ask-before-spending",
+  "--ask-before-external-messages",
+  "--ask-before-production-changes",
+  "--ask-before-secrets",
+]);
+
+function positionalArgs() {
+  const positionals: string[] = [];
+  for (let i = 0; i < filteredArgs.length; i++) {
+    if (filteredArgs[i].startsWith("--")) {
+      if (!BOOLEAN_FLAGS.has(filteredArgs[i])) {
+        i++;
+      }
+    } else {
+      positionals.push(filteredArgs[i]);
+    }
+  }
+  return positionals;
+}
+
+function positional(index: number) {
+  return positionalArgs()[index];
+}
+
+function positionalsFrom(index: number) {
+  return positionalArgs().slice(index);
+}
+
+function print(value: unknown) {
+  if (json) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  if (typeof value === "string") {
+    console.log(value);
+    return;
+  }
+  console.log(JSON.stringify(value, null, 2));
+}
+
+function stringArrayField(record: JsonRecord | undefined, name: string) {
+  const value = record?.[name];
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function throwIfCliError(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return;
+  }
+  const record = value as JsonRecord;
+  if (record.ok === false && typeof record.error === "string") {
+    throw new Error(record.error);
+  }
+}
+
+function parseJsonObjectOption(name: string) {
+  const raw = option(name);
+  if (!raw) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    throw new CliError(`${name} must be valid JSON`, {
+      code: "malformed_json",
+      option: name,
+      nextActions: [
+        `Pass ${name} as a quoted JSON object, for example: ${name} '{"key":"value"}'`,
+        "Use --json for structured CLI output.",
+      ],
+    });
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new CliError(`${name} must be a JSON object`, {
+      code: "malformed_json",
+      option: name,
+      nextActions: [
+        `Pass ${name} as an object, for example: ${name} '{"key":"value"}'`,
+      ],
+    });
+  }
+  return parsed as JsonRecord;
+}
+
+function parseNumberOption(name: string) {
+  const raw = option(name);
+  if (!raw) return undefined;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    throw new CliError(`${name} must be a number`, {
+      code: "invalid_number",
+      option: name,
+      nextActions: [`Retry with a numeric value for ${name}.`],
+    });
+  }
+  return parsed;
+}
+
+function parseCommaOption(name: string) {
+  return (
+    option(name)
+      ?.split(",")
+      .map((item) => item.trim())
+      .filter(Boolean) ?? []
+  );
+}
+
+function logHuman(message: string) {
+  if (!json) {
+    console.error(message);
+  }
+}
+
+function help() {
+  console.log(`Dench CLI
+
+Usage:
+  dench onboard [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
+  dench setup [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
+  dench what-can-i-do [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
+  dench login [--host ${DEFAULT_HOST}] [--name "Claude Code Agent"] [--kind <kind>] [--no-open]
+  dench sessions [--host <host>] [--json]
+  dench use <session-key-or-workspace-slug> [--host <host>] [--json]
+  dench logout [session-key-or-workspace-slug] [--session <key-or-scope>] [--host <host>] [--all] [--json]
+  dench context [--json]
+  dench status [--mine|--self] [--json]
+  dench tasks [--json]
+  dench task create "title" [--description "..."] [--priority low|medium|high] [--risk low|medium|high] [--json]
+  dench task status <taskId> <open|claimed|in_progress|waiting_approval|completed|canceled> [--note "..."] [--json]
+  dench task comment <taskId> "message" [--json]
+  dench task handoff <taskId> "message" --agent <agentId> [--json]
+  dench task block <taskId> "message" [--json]
+  dench claim <taskId> [--json]
+  dench log "message" [--task <taskId>] [--json]
+  dench memory search "query" [--limit 8] [--json]
+  dench memory save <key> "text" [--kind fact|decision|preference|goal|tool_note|other] [--tags a,b] [--sensitivity normal|broad|sensitive] [--json]
+  dench artifacts [--limit 25] [--json]
+  dench suggested-work [--json]
+  dench suggested-work task <artifactId> [--json]
+  dench approval request "message" [--task <taskId>] [--json]
+  dench approval approve <approvalId> [--evidence "User said yes in chat"] [--json]
+  dench approval reject <approvalId> [--evidence "User said no in chat"] [--json]
+  dench billing status [--json]
+  dench billing topup --amount 5 [--no-open] [--json]
+  dench apps [--json]
+  dench tool status [toolkit] [--json]
+  dench tool connect <toolkit> [--json]
+  dench tool search "create github issue" [--toolkit github] [--limit 20] [--compact] [--json]
+  dench tool run <composio_tool_slug> --args '{"key":"value"}' [--account <connected_account_id>] [--approval <approvalId>] [--json]
+  dench autonomous run "Inspect this repo and summarize the relevant feature. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." [--duration 1h] [--model <model>] [--api-base http://localhost:3000] [--json]
+
+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 cells <get|set|append> <object> <entryId> <field> [value]
+  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>
+  dench crm search [--object <name>] [--limit N] <text>
+  dench crm import <object> --csv <path> [--map '{...}'] [--on-conflict skip|update|error]
+  dench crm export <object> --format csv|jsonl [--limit N]
+  dench crm transaction <begin|add|commit|abort|inspect>
+  dench crm people|companies <search|upsert|enrich> ...
+  dench crm enrich <cell|object> ...
+  dench crm reports generate <name> --object <obj> --type pie|bar|line|table --group-by <field>
+  dench crm docs <list|create|link>
+  dench crm actions <list|run> ...
+  dench crm batch --file ops.jsonl
+  Help: dench crm help
+
+File sync (Daytona-native rewrite):
+  dench fs sync --initial --org-id <orgId> [--workspace /workspace]
+  dench fs stream-open <path>
+  dench fs stream-append <token> <chunk>
+  dench fs stream-close <token>
+
+Subagents (Daytona-native rewrite):
+  dench agent spawn '<goal>' [--parent-run-id <id>] [--sandbox own|share_parent] [--time-budget-ms N]
+  dench agent await --hook <token> | --children id1,id2,id3
+  dench agent message <toRunId> '<text>' [--from-run-id <id>]
+  dench agent wait-message
+  dench agent pause <runId>
+  dench agent resume <runId> ['optional prompt']
+  dench agent continue <prevRunId> '<prompt>'
+  dench agent tree [<rootRunId>]
+  Help: dench agent help
+
+  dench --version
+
+External tools:
+  dench apps is an alias for dench tool status -- it lists connected apps.
+  dench tool with no subcommand prints tool help.
+  Read-only FETCH, GET, LIST, SEARCH, READ, and FIND tools do not need manual approval.
+
+Billing:
+  dench billing status shows current AI credits.
+  dench billing topup --amount 5 creates a Stripe Checkout link for the human to pay.
+
+Agent setup:
+  dench onboard wraps login (when needed), workspace orientation, tasks, tools,
+  suggested work, memory, and next recommended actions.
+  --kind accepts any string. Suggested values: claude_code, codex, cursor,
+  hermes, openclaw, or any custom kind (e.g. aider, goose, internal_orchestrator).
+  Defaults to "other" when omitted. Values are normalized to lowercase
+  snake_case before send (e.g. "Claude Code" -> claude_code).
+  After login approval, run dench status --mine --json and dench tasks --json.
+  Use dench memory and dench artifacts to continue from durable context.
+  Do not create, claim, or log a setup task by default.
+
+Hosts:
+  Default production host: ${DEFAULT_HOST}
+  Staging: dench login --staging
+  Staging with explicit host: dench login --host ${STAGING_HOST}
+
+Dev fallback:
+  DENCH_DEV_AGENT_KEY=... DENCH_WORKSPACE=... NEXT_PUBLIC_CONVEX_URL=... dench status --dev
+
+Advanced:
+  For long-lived agents or when the human asks:
+    DENCH_SESSION_KEY=stable-agent-id dench login
+    DENCH_SESSION_KEY=stable-agent-id dench logout
+    DENCH_SESSION_KEY=stable-agent-id dench status
+`);
+}
+
+function toolHelp() {
+  console.log(`Dench tool commands
+
+Usage:
+  dench apps [--json]
+  dench tool status [toolkit] [--json]
+  dench tool connect <toolkit> [--json]
+  dench tool search "create github issue" [--toolkit github] [--limit 20] [--compact] [--json]
+  dench tool run <composio_tool_slug> --args '{"key":"value"}' [--account <connected_account_id>] [--approval <approvalId>] [--json]
+
+Notes:
+  dench apps lists all connected apps. It returns the same shape as dench tool status --json.
+  dench tool search prints compact ranked results by default. Add --json only when you need full schemas.
+  Run clear read-only FETCH, GET, LIST, SEARCH, READ, and FIND tools through Dench without manual approval.
+  Non-JSON tool run output redacts likely OTP codes, secrets, and tokens for display.
+  Dench enforces the final policy and returns requiresApproval when approval is needed.
+`);
+}
+
+function autonomousHelp() {
+  console.log(`Dench Long Session commands
+
+Usage:
+  dench autonomous run "Inspect this repo and summarize the relevant feature. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." [--duration 1h] [--model <model>] [--api-base http://localhost:3000] [--json]
+
+Notes:
+  Starts a Long Session through /api/runs.
+  Duration supports 30m, 1h, 3h, 5h, or until-done.
+  API base defaults to ${AUTONOMOUS_DEFAULT_API_BASE}.
+  Override with --api-base, --host, DENCH_AUTONOMOUS_API_BASE, or DENCH_HOST.
+  If needed, run dench login --host <api-base> once so the CLI can authenticate.
+  Omit --model to use the server default.
+  Approval flags: --ask-before-publishing --ask-before-spending --ask-before-external-messages --ask-before-production-changes --ask-before-secrets.
+  Safe goals should explicitly say: ${SAFE_LONG_SESSION_CONSTRAINTS.join(", ")}.
+`);
+}
+
+function contextHelp() {
+  console.log(`Dench context
+
+Usage:
+  dench context [--json]
+
+Shows the current workspace, current agent, assigned tasks, pending approvals
+requested by this agent, connected apps when available, and useful next commands.
+`);
+}
+
+function memoryHelp() {
+  console.log(`Dench memory
+
+Usage:
+  dench memory search "query" [--limit 8] [--json]
+  dench memory save <key> "text" [--kind fact|decision|preference|goal|tool_note|other] [--tags a,b] [--sensitivity normal|broad|sensitive] [--json]
+
+Use memory only for stable facts, decisions, preferences, recurring goals, and
+tool notes. Do not store secrets or scratch notes.
+`);
+}
+
+function artifactsHelp() {
+  console.log(`Dench artifacts
+
+Usage:
+  dench artifacts [--limit 25] [--json]
+  dench suggested-work [--json]
+  dench suggested-work task <artifactId> [--json]
+
+Artifacts are durable Long Session outputs for human or agent review.
+Suggested work can be converted into a workspace task.
+`);
+}
+
+function onboardHelp() {
+  console.log(`Dench onboard
+
+Usage:
+  dench onboard [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
+  dench setup [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
+  dench what-can-i-do [--kind <kind>] [--name "AI Agent - Project"] [--no-open] [--json]
+
+Logs in if needed, then shows what this agent can do here: workspace rules,
+open work, suggested work, Long Session options, connected-tool commands,
+memory, approvals, and next actions.
+`);
+}
+
+function loginHelp() {
+  console.log(`Dench login
+
+Usage:
+  dench login [--name "AI Agent - Billing Repo"] [--kind <kind>] [--host <host>] [--no-open]
+
+Agent kind:
+  --kind accepts any string. Defaults to "other" when omitted.
+  Suggested values: claude_code, codex, cursor, hermes, openclaw, or any
+  custom kind such as aider, goose, or some_custom_agent. Values are
+  normalized to lowercase snake_case before send (e.g. "Claude Code"
+  becomes claude_code, "my agent" becomes my_agent).
+
+Agent setup:
+  Claude Code: dench login --kind claude_code --name "Claude Code Agent - Project"
+  Codex: dench login --kind codex --name "Codex Agent - Project"
+  Cursor: dench login --kind cursor --name "Cursor Agent - Project"
+  Custom: dench login --kind some_custom_agent --name "My Agent - Project"
+  After approval, run dench status --mine --json and dench tasks --json.
+`);
+}
+
+function statusHelp() {
+  console.log(`Dench status
+
+Usage:
+  dench status [--mine|--self] [--json]
+
+Notes:
+  --mine and --self return the current workspace, current agent, counts, rules,
+  assigned tasks, and pending approvals requested by this agent.
+  Use dench status --mine --json during setup verification.
+`);
+}
+
+function tasksHelp() {
+  console.log(`Dench tasks
+
+Usage:
+  dench tasks [--json]
+
+Notes:
+  List workspace tasks before creating new ones.
+  Do not create, claim, or log a setup task by default.
+  Only create or claim a task if the human assigns work, an open matching task
+  exists, or coordination benefits from creating one.
+`);
+}
+
+function logoutHelp() {
+  console.log(`Dench logout
+
+Usage:
+  dench logout [session-key-or-workspace-slug] [--session <key-or-scope>] [--host <host>] [--all] [--json]
+
+Notes:
+  dench logout removes only the current selected session for this local agent context.
+  Other saved sessions can still be reused by future chats until removed.
+  Use dench logout --all to clear every saved Dench session on this machine.
+`);
+}
+
+function appsHelp() {
+  console.log(`Dench apps
+
+Usage:
+  dench apps [--json]
+
+Lists all connected external apps for the current Dench session.
+This is an alias for dench tool status [--json].
+`);
+}
+
+function billingHelp() {
+  console.log(`Dench billing
+
+Usage:
+  dench billing status [--json]
+  dench billing topup --amount 5 [--no-open] [--json]
+
+Notes:
+  status shows the current AI credit balance for this workspace.
+  topup creates a Stripe Checkout link. The human opens the link and pays.
+`);
+}
+
+function resolveHost(config: ConfigFile | undefined, scope: SessionScope) {
+  return resolveHostFromArgs(filteredArgs, resolveConfigHost(config, scope));
+}
+
+async function loadConfig(): Promise<ConfigFile> {
+  try {
+    return JSON.parse(await readFile(CONFIG_PATH, "utf8")) as ConfigFile;
+  } catch {
+    return {};
+  }
+}
+
+async function saveConfig(nextConfig: ConfigFile) {
+  await mkdir(CONFIG_DIR, { recursive: true });
+  await writeFile(CONFIG_PATH, `${JSON.stringify(nextConfig, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await chmod(CONFIG_PATH, 0o600).catch(() => {});
+}
+
+async function saveSession(session: StoredSession, scope: SessionScope) {
+  const config = await loadConfig();
+  await saveConfig(withSavedSession(config, session, scope).config);
+}
+
+async function getStoredSession(host: string, scope: SessionScope) {
+  const config = await loadConfig();
+  return selectStoredSession(config, host, scope);
+}
+
+function formatTime(value: number | undefined) {
+  return value ? new Date(value).toISOString() : null;
+}
+
+function workspaceLabel(session: StoredSession) {
+  if (!session.organization) return "unknown workspace";
+  const slug = session.organization.slug;
+  return slug
+    ? `${session.organization.name} (${slug})`
+    : session.organization.name;
+}
+
+function loginNextCommandsMessage(
+  session: StoredSession,
+  stableSessionKey: string | undefined,
+) {
+  const workspaceName = session.organization?.name ?? "unknown workspace";
+  const workspaceSlug = session.organization?.slug ?? "unknown";
+  const agentName = session.agent?.name ?? "unknown agent";
+  const stableKeyText = stableSessionKey
+    ? ` Stable session key: ${stableSessionKey}.`
+    : "";
+  return `Next commands will use workspace ${workspaceName} (${workspaceSlug}) as ${agentName}.${stableKeyText}`;
+}
+
+function ambiguousSessionMessage(
+  config: ConfigFile,
+  scope: SessionScope,
+  host: string,
+) {
+  return `Multiple Dench sessions exist for ${host}, but none match this local agent context.
+${formatSessionChoices(config, scope, host)}
+Run dench sessions to list sessions.
+Run dench use <session-key-or-workspace-slug> to select one.
+For long-lived agents or when the human asks, use DENCH_SESSION_KEY=<stable-human-readable-id> at login time.`;
+}
+
+function summarizeSessionEntry(
+  entry: StoredSessionEntry<StoredSession>,
+  currentKey: string | undefined,
+) {
+  return {
+    sessionKey: entry.key,
+    current: entry.key === currentKey,
+    host: entry.host,
+    workspace: entry.session.organization
+      ? {
+          name: entry.session.organization.name,
+          slug: entry.session.organization.slug ?? null,
+          id: entry.session.organization.id,
+        }
+      : null,
+    agent: entry.session.agent
+      ? {
+          name: entry.session.agent.name,
+          kind: entry.session.agent.kind,
+          id: entry.session.agent.id,
+        }
+      : null,
+    scope: {
+      label: entry.session.sessionScopeLabel ?? null,
+      key: entry.session.sessionScope ?? null,
+    },
+    savedAt: entry.session.savedAt ?? null,
+    savedAtIso: formatTime(entry.session.savedAt),
+    expiresAt: entry.session.sessionExpiresAt ?? null,
+    expiresAtIso: formatTime(entry.session.sessionExpiresAt),
+  };
+}
+
+function formatSessionLine(
+  entry: StoredSessionEntry<StoredSession>,
+  currentKey: string | undefined,
+) {
+  const marker = entry.key === currentKey ? "* " : "  ";
+  const agent = entry.session.agent
+    ? `${entry.session.agent.name} [${entry.session.agent.kind}]`
+    : "unknown agent";
+  const scope = entry.session.sessionScopeLabel
+    ? `${entry.session.sessionScopeLabel}: ${entry.session.sessionScope ?? "unknown"}`
+    : (entry.session.sessionScope ?? "unknown scope");
+  const saved = formatTime(entry.session.savedAt) ?? "unknown";
+  const expires = formatTime(entry.session.sessionExpiresAt) ?? "unknown";
+  return `${marker}${entry.key}
+    host: ${entry.host}
+    workspace: ${workspaceLabel(entry.session)}
+    agent: ${agent}
+    scope: ${scope}
+    saved: ${saved}
+    expires: ${expires}`;
+}
+
+function sessionLines(config: ConfigFile, scope: SessionScope, host?: string) {
+  const resolvedHost = host ?? resolveHost(config, scope);
+  const selected = selectStoredSessionEntry(config, resolvedHost, scope);
+  const currentKey = selected.status === "found" ? selected.key : undefined;
+  return listStoredSessionEntries(config, host).map((entry) =>
+    formatSessionLine(entry, currentKey),
+  );
+}
+
+function formatSessionChoices(
+  config: ConfigFile,
+  scope: SessionScope,
+  host?: string,
+) {
+  const lines = sessionLines(config, scope, host);
+  return lines.length > 0 ? lines.join("\n") : "  No Dench sessions found.";
+}
+
+async function listSessions() {
+  const config = await loadConfig();
+  const scope = resolveSessionScope({ args: filteredArgs });
+  const host = option("--host") ? resolveHostFromArgs(filteredArgs) : undefined;
+  const selected = selectStoredSessionEntry(
+    config,
+    host ?? resolveHost(config, scope),
+    scope,
+  );
+  const currentKey = selected.status === "found" ? selected.key : undefined;
+  const entries = listStoredSessionEntries(config, host);
+
+  if (json) {
+    print(entries.map((entry) => summarizeSessionEntry(entry, currentKey)));
+    return;
+  }
+
+  if (entries.length === 0) {
+    print("No Dench sessions found.");
+    return;
+  }
+
+  print(
+    entries.map((entry) => formatSessionLine(entry, currentKey)).join("\n"),
+  );
+}
+
+function removeSessionEntries(
+  config: ConfigFile,
+  entries: Array<StoredSessionEntry<StoredSession>>,
+) {
+  const removedKeys = new Set(entries.map((entry) => entry.key));
+  const removedHosts = new Set(entries.map((entry) => entry.host));
+  const sessions = { ...(config.sessions ?? {}) };
+  for (const key of removedKeys) {
+    delete sessions[key];
+  }
+
+  const currentSessionKeys = { ...(config.currentSessionKeys ?? {}) };
+  const removedScopeKeys = new Set<string>();
+  for (const [scopeKey, key] of Object.entries(currentSessionKeys)) {
+    if (removedKeys.has(key)) {
+      delete currentSessionKeys[scopeKey];
+      removedScopeKeys.add(scopeKey);
+    }
+  }
+
+  const currentHosts = { ...(config.currentHosts ?? {}) };
+  for (const [scopeKey, host] of Object.entries(currentHosts)) {
+    if (removedScopeKeys.has(scopeKey)) {
+      delete currentHosts[scopeKey];
+      continue;
+    }
+    const hasRemainingForHost = Object.values(sessions).some(
+      (session) => normalizeHost(session.host) === normalizeHost(host),
+    );
+    if (!hasRemainingForHost) {
+      delete currentHosts[scopeKey];
+    }
+  }
+
+  const nextConfig: ConfigFile = { ...config };
+  if (
+    nextConfig.currentSessionKey &&
+    removedKeys.has(nextConfig.currentSessionKey)
+  ) {
+    delete nextConfig.currentSessionKey;
+  }
+  if (Object.keys(sessions).length > 0) {
+    nextConfig.sessions = sessions;
+  } else {
+    delete nextConfig.sessions;
+  }
+  if (Object.keys(currentSessionKeys).length > 0) {
+    nextConfig.currentSessionKeys = currentSessionKeys;
+  } else {
+    delete nextConfig.currentSessionKeys;
+  }
+  if (Object.keys(currentHosts).length > 0) {
+    nextConfig.currentHosts = currentHosts;
+  } else {
+    delete nextConfig.currentHosts;
+  }
+  if (
+    nextConfig.currentHost &&
+    removedHosts.has(normalizeHost(nextConfig.currentHost)) &&
+    !Object.values(sessions).some(
+      (session) =>
+        normalizeHost(session.host) ===
+        normalizeHost(nextConfig.currentHost ?? ""),
+    )
+  ) {
+    delete nextConfig.currentHost;
+  }
+  return nextConfig;
+}
+
+function plural(count: number, singular: string, pluralForm = `${singular}s`) {
+  return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+
+function logoutRemainingSummary(config: ConfigFile, host?: string) {
+  return {
+    total: listStoredSessionEntries(config).length,
+    forHost: host ? listStoredSessionEntries(config, host).length : undefined,
+  };
+}
+
+function logoutNextActions(
+  remaining: { total: number; forHost?: number },
+  host?: string,
+) {
+  if (remaining.total === 0) return [];
+  const actions = [
+    "Run dench sessions --json to inspect remaining saved sessions.",
+  ];
+  if (host && (remaining.forHost ?? 0) > 0) {
+    actions.push(
+      `Run dench logout --all --host ${host} to clear saved sessions for this host.`,
+    );
+  }
+  actions.push(
+    "Run dench logout --all to clear every saved Dench session on this machine.",
+  );
+  return actions;
+}
+
+function formatLogoutMessage(
+  primary: string,
+  remaining: { total: number; forHost?: number },
+  host?: string,
+) {
+  const lines = [primary];
+  if (host && (remaining.forHost ?? 0) > 0) {
+    lines.push(
+      `There ${remaining.forHost === 1 ? "is" : "are"} still ${plural(
+        remaining.forHost ?? 0,
+        "saved Dench session",
+      )} for ${host}. A future chat can reuse one if it is selected.`,
+    );
+  } else if (remaining.total > 0) {
+    lines.push(
+      `There ${remaining.total === 1 ? "is" : "are"} still ${plural(
+        remaining.total,
+        "saved Dench session",
+      )} on this machine.`,
+    );
+  }
+  const actions = logoutNextActions(remaining, host);
+  if (actions.length > 0) {
+    lines.push("Next actions:", ...actions.map((action) => `  - ${action}`));
+  }
+  return lines.join("\n");
+}
+
+async function selectSession() {
+  const selector = positional(1);
+  if (!selector) {
+    throw new Error(
+      "Missing session key or workspace slug. Run: dench sessions",
+    );
+  }
+
+  const config = await loadConfig();
+  const scope = resolveSessionScope({ args: filteredArgs });
+  const host = option("--host") ? resolveHostFromArgs(filteredArgs) : undefined;
+  const matches = findStoredSessionEntries(config, selector, host);
+  if (matches.length === 0) {
+    throw new Error(
+      `No Dench session matched "${selector}". Run dench sessions to see available sessions.`,
+    );
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      `More than one Dench session matched "${selector}". Choose the exact session key:\n${matches
+        .map((entry) => formatSessionLine(entry, undefined))
+        .join("\n")}`,
+    );
+  }
+
+  const [entry] = matches;
+  await saveConfig({
+    ...withCurrentSessionSelection(config, {
+      host: entry.host,
+      scope,
+      sessionKey: entry.key,
+    }),
+  });
+
+  print(
+    json
+      ? { ok: true, session: summarizeSessionEntry(entry, entry.key) }
+      : `Now using Dench session ${entry.key} for ${workspaceLabel(entry.session)}.`,
+  );
+}
+
+async function logout() {
+  const config = await loadConfig();
+  const scope = resolveSessionScope({ args: filteredArgs });
+  const host = option("--host") ? resolveHostFromArgs(filteredArgs) : undefined;
+  const selector = option("--session") ?? positional(1);
+
+  if (hasFlag("--all")) {
+    if (selector) {
+      throw new Error("Use either --all or a specific session, not both.");
+    }
+    const entries = listStoredSessionEntries(config, host);
+    const removed = entries.length;
+    const nextConfig = host
+      ? removeSessionEntries(config, entries)
+      : removeAllStoredSessions(config);
+    const remaining = logoutRemainingSummary(nextConfig, host);
+    if (
+      removed > 0 ||
+      config.currentHost ||
+      config.currentSessionKey ||
+      config.currentHosts ||
+      config.currentSessionKeys
+    ) {
+      await saveConfig(nextConfig);
+    }
+    print(
+      json
+        ? {
+            ok: true,
+            removed,
+            all: true,
+            host: host ?? null,
+            remainingSessions: remaining.total,
+            remainingHostSessions: remaining.forHost ?? null,
+            nextActions: logoutNextActions(remaining, host),
+          }
+        : removed > 0
+          ? formatLogoutMessage(
+              `Logged out of ${plural(removed, "Dench session")}.`,
+              remaining,
+              host,
+            )
+          : "No Dench sessions found.",
+    );
+    return;
+  }
+
+  if (selector) {
+    const matches = findStoredSessionEntries(config, selector, host);
+    if (matches.length === 0) {
+      throw new Error(
+        `No Dench session matched "${selector}". Run dench sessions to see available sessions.`,
+      );
+    }
+    if (matches.length > 1) {
+      throw new Error(
+        `More than one Dench session matched "${selector}". Choose the exact session key:\n${matches
+          .map((entry) => formatSessionLine(entry, undefined))
+          .join("\n")}`,
+      );
+    }
+
+    const nextConfig = removeSessionEntries(config, matches);
+    const remaining = logoutRemainingSummary(nextConfig, matches[0].host);
+    await saveConfig(nextConfig);
+    print(
+      json
+        ? {
+            ok: true,
+            removed: 1,
+            all: false,
+            sessionKey: matches[0].key,
+            remainingSessions: remaining.total,
+            remainingHostSessions: remaining.forHost ?? null,
+            nextActions: logoutNextActions(remaining, matches[0].host),
+          }
+        : formatLogoutMessage(
+            `Logged out of Dench session ${matches[0].key}.`,
+            remaining,
+            matches[0].host,
+          ),
+    );
+    return;
+  }
+
+  const resolvedHost = host ?? resolveHost(config, scope);
+  const result = removeStoredSession(config, resolvedHost, scope);
+
+  if (result.status === "ambiguous") {
+    throw new Error(ambiguousSessionMessage(config, scope, resolvedHost));
+  }
+
+  if (result.status === "missing") {
+    print(
+      json
+        ? {
+            ok: true,
+            removed: 0,
+            all: false,
+            host: resolvedHost,
+            sessionScope: scope.label,
+          }
+        : `No Dench session found for ${resolvedHost} in this local agent context.`,
+    );
+    return;
+  }
+
+  await saveConfig(result.config);
+  const remaining = logoutRemainingSummary(result.config, resolvedHost);
+  print(
+    json
+      ? {
+          ok: true,
+          removed: 1,
+          all: false,
+          host: resolvedHost,
+          sessionScope: scope.label,
+          sessionKey: result.removedKey,
+          remainingSessions: remaining.total,
+          remainingHostSessions: remaining.forHost ?? null,
+          nextActions: logoutNextActions(remaining, resolvedHost),
+        }
+      : formatLogoutMessage(
+          `Logged out of Dench session ${result.removedKey}.`,
+          remaining,
+          resolvedHost,
+        ),
+  );
+}
+
+function randomUrlSafe(bytes = 32) {
+  const values = new Uint8Array(bytes);
+  crypto.getRandomValues(values);
+  return Buffer.from(values)
+    .toString("base64")
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+}
+
+function cleanNameSegment(value: string) {
+  return value
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 24);
+}
+
+function localUsername() {
+  const fromEnv = process.env.USER ?? process.env.USERNAME;
+  if (fromEnv?.trim()) return fromEnv;
+
+  try {
+    return userInfo().username;
+  } catch {
+    return undefined;
+  }
+}
+
+function defaultAgentName(kind: string) {
+  const username = cleanNameSegment(localUsername() ?? "");
+  const machine = cleanNameSegment(hostname().split(".")[0] ?? "");
+  const localPart = [username, machine].filter(Boolean).join("@");
+  const uniquePart = randomUrlSafe(3).slice(0, 4).toLowerCase();
+  const suffix = [localPart, uniquePart].filter(Boolean).join("-");
+
+  return `${agentKindLabel(kind)} (${suffix})`;
+}
+
+function resolveAgentName(kind: string) {
+  return option("--name")?.trim() || defaultAgentName(kind);
+}
+
+async function sha256Hex(input: string) {
+  const bytes = new TextEncoder().encode(input);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function discoverConvexUrl(host: string) {
+  const explicit = option("--convex-url");
+  if (explicit) return explicit.trim();
+  if (isLocalHost(host) && process.env.NEXT_PUBLIC_CONVEX_URL) {
+    return process.env.NEXT_PUBLIC_CONVEX_URL.trim();
+  }
+
+  const response = await fetch(`${host}/api/agent-config`);
+  if (!response.ok) {
+    throw new Error(`Could not load Dench config from ${host}`);
+  }
+  const payload = (await response.json()) as { convexUrl?: string };
+  if (!payload.convexUrl) {
+    throw new Error(`Dench config at ${host} is missing convexUrl`);
+  }
+  return payload.convexUrl;
+}
+
+async function login() {
+  const scope = resolveSessionScope({ args: filteredArgs });
+  const explicitKey = explicitSessionKeyInput({ args: filteredArgs });
+  const host = resolveHostFromArgs(filteredArgs, undefined);
+  const convexUrl = await discoverConvexUrl(host);
+  const client = new ConvexHttpClient(convexUrl);
+  const code = randomUrlSafe(18);
+  const sessionToken = `dch_agent_${randomUrlSafe(32)}`;
+  const codeHash = await sha256Hex(code);
+  const sessionTokenHash = await sha256Hex(sessionToken);
+  const agentKind = normalizeAgentKind(option("--kind"));
+  const agentName = resolveAgentName(agentKind);
+  const request = await client.mutation(
+    api.functions.agentWorkspace.createAgentLoginRequest,
+    {
+      codeHash,
+      sessionTokenHash,
+      agentName,
+      agentKind,
+      userAgent: "dench-cli",
+    },
+  );
+  const approvalUrl = `${host}/agent-login/${encodeURIComponent(code)}`;
+
+  const openResult = await openUrl(approvalUrl, {
+    noOpen: hasFlag("--no-open"),
+    json,
+    env: process.env,
+  });
+  logHuman(formatApprovalOpenMessage(approvalUrl, openResult));
+  logHuman(
+    "Before approving, switch Dench in your browser to the intended workspace.",
+  );
+  logHuman(
+    `This request expires at ${new Date(request.expiresAt).toLocaleString()}.`,
+  );
+
+  const timeoutMs = Number(option("--timeout-ms") ?? 15 * 60 * 1000);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const poll = await client.mutation(
+      api.functions.agentWorkspace.pollAgentLoginRequest,
+      { codeHash, sessionTokenHash },
+    );
+
+    if (poll.status === "approved") {
+      const storedSession: StoredSession = {
+        host,
+        convexUrl,
+        sessionToken,
+        organization: poll.organization,
+        agent: poll.agent,
+        sessionExpiresAt: poll.sessionExpiresAt,
+        savedAt: Date.now(),
+      };
+      await saveSession(storedSession, scope);
+      const message = loginNextCommandsMessage(
+        storedSession,
+        explicitKey?.source === "DENCH_SESSION_KEY"
+          ? explicitKey.value
+          : undefined,
+      );
+      print(
+        json
+          ? {
+              ok: true,
+              host,
+              organization: poll.organization,
+              agent: poll.agent,
+              sessionExpiresAt: poll.sessionExpiresAt,
+              message,
+            }
+          : message,
+      );
+      return;
+    }
+    if (poll.status === "rejected" || poll.status === "expired") {
+      throw new Error(`Login ${poll.status}`);
+    }
+
+    await sleep(2000);
+  }
+
+  throw new Error(`Login timed out. Open ${approvalUrl} and run login again.`);
+}
+
+function normalizeApiBase(input: string) {
+  const trimmed = input.trim();
+  const withProtocol = /^https?:\/\//.test(trimmed)
+    ? trimmed
+    : /^(localhost|127\.0\.0\.1|\[::1\])(?::|$)/.test(trimmed)
+      ? `http://${trimmed}`
+      : `https://${trimmed}`;
+  return new URL(withProtocol).origin;
+}
+
+function resolveAutonomousApiBase() {
+  const explicit =
+    option("--api-base") ??
+    option("--host") ??
+    process.env.DENCH_AUTONOMOUS_API_BASE ??
+    process.env.DENCH_HOST;
+  return explicit ? normalizeApiBase(explicit) : AUTONOMOUS_DEFAULT_API_BASE;
+}
+
+async function resolveAutonomousSessionToken(apiBase: string) {
+  const config = await loadConfig();
+  const scope = resolveSessionScope({ args: filteredArgs });
+  const stored = await getStoredSession(apiBase, scope);
+  if (stored.status === "found") {
+    return stored.session.sessionToken;
+  }
+  if (stored.status === "ambiguous") {
+    throw new Error(ambiguousSessionMessage(config, scope, apiBase));
+  }
+  return undefined;
+}
+
+function formatAutonomousRunResult(value: unknown) {
+  const record = asRecord(value);
+  if (!record) {
+    return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  }
+
+  const runId = stringField(record, "runId", "id");
+  const workflowRunId = stringField(record, "workflowRunId");
+  const status = stringField(record, "status");
+  const url = stringField(record, "url", "runUrl");
+
+  if (!runId && !workflowRunId && !status && !url) {
+    return JSON.stringify(value, null, 2);
+  }
+
+  const lines = ["Started Long Session"];
+  if (runId) lines.push(`Run ID: ${runId}`);
+  if (workflowRunId) lines.push(`Workflow Run ID: ${workflowRunId}`);
+  if (status) lines.push(`Status: ${status}`);
+  if (url) lines.push(`URL: ${url}`);
+  return lines.join("\n");
+}
+
+function autonomousRunUrl(apiBase: string, runId: string) {
+  return `${apiBase.replace(/\/+$/, "")}/labs/autonomous/${encodeURIComponent(runId)}`;
+}
+
+function withAutonomousRunUrl(payload: unknown, apiBase: string) {
+  const record = asRecord(payload);
+  const runId = stringField(record, "runId", "id");
+  if (!record || !runId || stringField(record, "runUrl", "url")) {
+    return payload;
+  }
+  return { ...record, runUrl: autonomousRunUrl(apiBase, runId) };
+}
+
+function formatAutonomousRunError(args: {
+  status: number;
+  payload: unknown;
+  apiBase: string;
+  hasSession: boolean;
+  statusText: string;
+}) {
+  const record = asRecord(args.payload);
+  const error =
+    stringField(record, "error", "message") ??
+    (typeof args.payload === "string" && args.payload.trim()
+      ? args.payload.trim()
+      : args.statusText);
+  const nextActions = stringArrayField(record, "nextActions");
+  if (args.status === 401 && !args.hasSession) {
+    nextActions.unshift(`Run: dench login --host ${args.apiBase}`);
+  } else if (args.status === 401) {
+    nextActions.push(
+      "Run dench sessions --json to inspect saved sessions.",
+      `Run dench login --host ${args.apiBase} if this session is expired.`,
+    );
+  } else if (args.status === 402 && nextActions.length === 0) {
+    nextActions.push(
+      "Top up AI credits in Dench usage/billing.",
+      "Retry the same Long Session command after credits update.",
+    );
+  }
+  if (stringField(record, "topUpUrl")) {
+    nextActions.unshift(`Top up: ${stringField(record, "topUpUrl")}`);
+  }
+  return new CliError(`Long Session failed (${args.status}): ${error}`, {
+    status: args.status,
+    code: stringField(record, "code") ?? `http_${args.status}`,
+    apiBase: args.apiBase,
+    topUpUrl: stringField(record, "topUpUrl"),
+    nextActions: [...new Set(nextActions)],
+  });
+}
+
+function safeLongSessionExample() {
+  return 'dench autonomous run "Inspect this repo and summarize the relevant feature. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." --duration 30m';
+}
+
+function parseDurationMs(rawDuration?: string) {
+  const raw = rawDuration?.trim().toLowerCase();
+  if (!raw) return undefined;
+  if (["until-done", "until_done", "done", "max"].includes(raw)) {
+    return 24 * 60 * 60 * 1000;
+  }
+  const match = raw.match(
+    /^(\d+(?:\.\d+)?)(m|min|mins|minute|minutes|h|hr|hrs|hour|hours)$/,
+  );
+  if (!match) {
+    throw new CliError(
+      "--duration must look like 30m, 1h, 3h, 5h, or until-done",
+      {
+        code: "invalid_duration",
+        nextActions: [
+          "Use one of: 30m, 1h, 3h, 5h, until-done.",
+          safeLongSessionExample(),
+        ],
+      },
+    );
+  }
+  const value = Number(match[1]);
+  const unit = match[2];
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new CliError("--duration must be positive", {
+      code: "invalid_duration",
+      nextActions: ["Use a positive duration like 30m or 1h."],
+    });
+  }
+  const minutes = unit.startsWith("h") ? value * 60 : value;
+  return Math.round(minutes * 60 * 1000);
+}
+
+function durationPreset(rawDuration?: string) {
+  const raw = rawDuration?.trim().toLowerCase();
+  if (!raw) return undefined;
+  return raw.replace("-", "_");
+}
+
+function parseApprovalRules() {
+  const explicit = option("--approval-rules")
+    ?.split(",")
+    .map((rule) => rule.trim())
+    .filter(Boolean);
+  if (explicit && explicit.length > 0) return explicit;
+  const rules: string[] = [];
+  if (hasFlag("--ask-before-publishing")) rules.push("publishing");
+  if (hasFlag("--ask-before-spending")) rules.push("spending");
+  if (hasFlag("--ask-before-external-messages")) {
+    rules.push("external_messages");
+  }
+  if (hasFlag("--ask-before-production-changes")) {
+    rules.push("production_changes");
+  }
+  if (hasFlag("--ask-before-secrets")) rules.push("secrets");
+  return rules.length > 0
+    ? rules
+    : [
+        "publishing",
+        "spending",
+        "external_messages",
+        "production_changes",
+        "secrets",
+      ];
+}
+
+async function parseResponseBody(response: Response) {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+async function startAutonomousRun() {
+  const goal = positionalsFrom(2).join(" ").trim();
+  if (!goal) {
+    throw new CliError("Missing goal", {
+      code: "missing_goal",
+      nextActions: [
+        safeLongSessionExample(),
+        "Keep the goal specific and include safety constraints for risky actions.",
+      ],
+    });
+  }
+
+  const model = option("--model")?.trim();
+  const duration = option("--duration");
+  const body: JsonRecord = {
+    goal,
+    metadata: {
+      sessionKind: "long_session",
+      approvalRules: parseApprovalRules(),
+      safetyConstraints: SAFE_LONG_SESSION_CONSTRAINTS,
+      ...(duration ? { durationPreset: durationPreset(duration) } : {}),
+    },
+  };
+  if (model) body.model = model;
+  const timeBudgetMs = parseDurationMs(duration);
+  if (timeBudgetMs) body.timeBudgetMs = timeBudgetMs;
+
+  const apiBase = resolveAutonomousApiBase();
+  const agentSessionToken = await resolveAutonomousSessionToken(apiBase);
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    "content-type": "application/json",
+  };
+  if (agentSessionToken) {
+    headers.authorization = `Bearer ${agentSessionToken}`;
+  }
+
+  const response = await fetch(`${apiBase}/api/runs`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  const payload = await parseResponseBody(response);
+
+  if (!response.ok) {
+    throw formatAutonomousRunError({
+      status: response.status,
+      payload,
+      apiBase,
+      hasSession: Boolean(agentSessionToken),
+      statusText: response.statusText,
+    });
+  }
+
+  const output = withAutonomousRunUrl(payload, apiBase);
+  throwIfCliError(output);
+  print(json ? output : formatAutonomousRunResult(output));
+}
+
+function formatUsd(cents: number | undefined) {
+  const value = typeof cents === "number" && Number.isFinite(cents) ? cents : 0;
+  return `$${(value / 100).toFixed(2)}`;
+}
+
+function formatBillingStatus(value: unknown) {
+  const record = asRecord(value);
+  if (!record) return JSON.stringify(value, null, 2);
+  const workspace = asRecord(record.workspace);
+  const workspaceName = stringField(workspace, "name") ?? "Workspace";
+  const workspaceSlug = stringField(workspace, "slug");
+  const lines = [
+    `Workspace: ${workspaceName}${workspaceSlug ? ` (${workspaceSlug})` : ""}`,
+    `AI credits: ${formatUsd(numberField(record, "availableCreditsCents"))} available`,
+    `Used credits: ${formatUsd(numberField(record, "creditConsumedCents"))}`,
+  ];
+  const status = stringField(record, "subscriptionStatus");
+  if (status) lines.push(`Billing status: ${status}`);
+  lines.push("", "Top up: dench billing topup --amount 5");
+  return lines.join("\n");
+}
+
+function parseBillingTopupAmountUsd() {
+  const raw = option("--amount") ?? positional(2);
+  const amount = Number(raw);
+  if (!raw || !Number.isFinite(amount) || amount <= 0) {
+    throw new CliError("Missing or invalid top-up amount", {
+      code: "invalid_topup_amount",
+      nextActions: ["Run dench billing topup --amount 5."],
+    });
+  }
+  return amount;
+}
+
+async function billingStatus(runtime: Runtime) {
+  const sessionRuntime = requireSessionRuntime(runtime, "dench billing status");
+  const status = await sessionRuntime.client.query(
+    api.functions.agentWorkspace.getAgentBillingStatus,
+    { sessionToken: sessionRuntime.sessionToken },
+  );
+  print(json ? status : formatBillingStatus(status));
+}
+
+async function billingTopup(runtime: Runtime) {
+  const sessionRuntime = requireSessionRuntime(runtime, "dench billing topup");
+  const amountUsd = parseBillingTopupAmountUsd();
+  const response = await fetch(
+    `${sessionRuntime.host.replace(/\/+$/, "")}/api/stripe/create-ai-topup`,
+    {
+      method: "POST",
+      headers: {
+        accept: "application/json",
+        "content-type": "application/json",
+        authorization: `Bearer ${sessionRuntime.sessionToken}`,
+      },
+      body: JSON.stringify({
+        amountUsd,
+        requestId: crypto.randomUUID(),
+      }),
+    },
+  );
+  const payload = await parseResponseBody(response);
+  if (!response.ok) {
+    const errorRecord = asRecord(payload);
+    throw new CliError(
+      stringField(errorRecord, "error", "message") ??
+        `Could not create top-up checkout (${response.status})`,
+      {
+        code: stringField(errorRecord, "code") ?? "topup_failed",
+        status: response.status,
+      },
+    );
+  }
+
+  const url = stringField(asRecord(payload), "url");
+  const openResult = url
+    ? await openUrl(url, {
+        noOpen: hasFlag("--no-open"),
+        json,
+        env: process.env,
+      })
+    : ({ status: "skipped", reason: "missing-url" } as const);
+  const openMessage =
+    url && openResult.status === "opened"
+      ? `Attempted to open Stripe Checkout in your browser. If it did not open, use this link: ${url}`
+      : url && openResult.status === "failed"
+        ? `Could not open browser automatically. Open this Stripe Checkout link: ${url}`
+        : url
+          ? `Open this Stripe Checkout link: ${url}`
+          : "Stripe Checkout link created.";
+  const output = {
+    ok: true,
+    amountUsd,
+    url,
+    openResult,
+    message: openMessage,
+  };
+  print(json ? output : output.message);
+}
+
+function hasDevEnv() {
+  return Boolean(
+    process.env.NEXT_PUBLIC_CONVEX_URL &&
+      process.env.DENCH_WORKSPACE &&
+      process.env.DENCH_DEV_AGENT_KEY,
+  );
+}
+
+function loginRequiredError(command = "this command") {
+  return new CliError(`${command} requires dench login`, {
+    code: "login_required",
+    nextActions: [
+      'Run dench onboard --kind <kind> --name "AI Agent - Project".',
+      "If already approved, run dench sessions --json, then dench use <session-key-or-workspace-slug>.",
+    ],
+  });
+}
+
+function missingDevEnvError() {
+  const required = [
+    "NEXT_PUBLIC_CONVEX_URL",
+    "DENCH_WORKSPACE",
+    "DENCH_DEV_AGENT_KEY",
+  ];
+  return new CliError("Missing Dench dev environment", {
+    code: "missing_dev_env",
+    missingEnv: required.filter((name) => !process.env[name]?.trim()),
+    nextActions: [
+      "Set NEXT_PUBLIC_CONVEX_URL, DENCH_WORKSPACE, and DENCH_DEV_AGENT_KEY.",
+      "Or remove --dev and run dench onboard to use a real agent session.",
+    ],
+  });
+}
+
+async function getRuntime() {
+  const scope = resolveSessionScope({ args: filteredArgs });
+  if (!hasFlag("--dev")) {
+    const config = await loadConfig();
+    const host = resolveHost(config, scope);
+    const stored = await getStoredSession(host, scope);
+    if (stored.status === "found") {
+      return {
+        mode: "session" as const,
+        host,
+        client: new ConvexHttpClient(stored.session.convexUrl),
+        sessionToken: stored.session.sessionToken,
+        organization: stored.session.organization,
+      };
+    }
+    if (stored.status === "ambiguous") {
+      throw new CliError(ambiguousSessionMessage(config, scope, host), {
+        code: "session_ambiguous",
+        nextActions: [
+          "Run dench sessions --json to inspect saved sessions.",
+          "Run dench use <session-key-or-workspace-slug> to select one.",
+        ],
+      });
+    }
+  }
+
+  if (!hasDevEnv()) {
+    throw hasFlag("--dev") ? missingDevEnvError() : loginRequiredError();
+  }
+
+  return {
+    mode: "dev" as const,
+    client: new ConvexHttpClient(readEnv("NEXT_PUBLIC_CONVEX_URL")),
+    workspaceArgs: {
+      devKey: readEnv("DENCH_DEV_AGENT_KEY"),
+      workspaceSlug: readEnv("DENCH_WORKSPACE"),
+    },
+  };
+}
+
+type Runtime = Awaited<ReturnType<typeof getRuntime>>;
+
+function requireSessionRuntime(
+  runtime: Runtime,
+  command: string,
+): Extract<Runtime, { mode: "session" }> {
+  if (runtime.mode !== "session") {
+    throw loginRequiredError(command);
+  }
+  return runtime;
+}
+
+async function printToolStatus(runtime: Runtime, toolkit?: string) {
+  const sessionRuntime = requireSessionRuntime(runtime, "dench tool status");
+  try {
+    print(
+      await sessionRuntime.client.action(
+        api.functions.agentToolsNode.agentToolStatus,
+        {
+          sessionToken: sessionRuntime.sessionToken,
+          toolkit,
+        },
+      ),
+    );
+  } catch (error) {
+    const unavailable = toolGatewayUnavailable(error, { toolkit });
+    if (!unavailable) throw error;
+    print(json ? unavailable : formatToolUnavailable(unavailable));
+  }
+}
+
+function asRecord(value: unknown): JsonRecord | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as JsonRecord;
+}
+
+function asRecordArray(value: unknown): JsonRecord[] {
+  return Array.isArray(value)
+    ? value.flatMap<JsonRecord>((item) => asRecord(item) ?? [])
+    : [];
+}
+
+function stringValue(value: unknown) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function stringField(record: JsonRecord | undefined, ...names: string[]) {
+  if (!record) return undefined;
+  for (const name of names) {
+    const value = stringValue(record[name]);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function numberField(record: JsonRecord | undefined, ...names: string[]) {
+  if (!record) return undefined;
+  for (const name of names) {
+    const value = record[name];
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return undefined;
+}
+
+function booleanField(record: JsonRecord | undefined, ...names: string[]) {
+  if (!record) return undefined;
+  for (const name of names) {
+    const value = record[name];
+    if (typeof value === "boolean") return value;
+  }
+  return undefined;
+}
+
+function compactLine(value: unknown, maxLength = 140) {
+  const text = stringValue(value)?.replace(/\s+/g, " ");
+  if (!text) return undefined;
+  return text.length > maxLength ? `${text.slice(0, maxLength - 1)}...` : text;
+}
+
+function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isMissingConvexFunction(error: unknown) {
+  return /Could not find public function/i.test(errorMessage(error));
+}
+
+function toolGatewayUnavailable(error: unknown, context: JsonRecord = {}) {
+  const message = errorMessage(error);
+  if (!/gateway API key|callGateway|Composio/i.test(message)) {
+    return null;
+  }
+  const invalidKey = /Invalid gateway API key/i.test(message);
+  const query = stringField(context, "query");
+  const toolkit = stringField(context, "toolkit");
+  const retryCommand = query
+    ? `Retry dench tool search ${JSON.stringify(query)}${toolkit ? ` --toolkit ${toolkit}` : ""} after the gateway key is fixed.`
+    : "Retry dench apps --json after the gateway key is fixed.";
+  return {
+    ok: false,
+    available: false,
+    code: invalidKey ? "invalid_gateway_api_key" : "tool_gateway_unavailable",
+    reason: invalidKey
+      ? "The workspace gateway key is invalid or out of sync."
+      : "The connected-app gateway is unavailable.",
+    ...context,
+    nextActions: [
+      "Ask a workspace admin to repair or rotate the Dench gateway key.",
+      retryCommand,
+    ],
+  };
+}
+
+function formatToolUnavailable(payload: JsonRecord) {
+  return [
+    "Connected apps unavailable.",
+    `Reason: ${stringField(payload, "reason") ?? "tool gateway unavailable"}`,
+    "",
+    "Next actions:",
+    ...(
+      (Array.isArray(payload.nextActions)
+        ? payload.nextActions
+        : []) as unknown[]
+    )
+      .filter((item): item is string => typeof item === "string")
+      .map((item) => `  - ${item}`),
+  ].join("\n");
+}
+
+const READ_ONLY_TOOL_ACTIONS = new Set([
+  "FETCH",
+  "GET",
+  "LIST",
+  "SEARCH",
+  "READ",
+  "FIND",
+]);
+
+function toolSlugTokens(toolSlug: string) {
+  return toolSlug
+    .toUpperCase()
+    .split(/[^A-Z0-9]+/)
+    .filter(Boolean);
+}
+
+function toolApprovalHint(toolSlug: string | undefined) {
+  if (!toolSlug) return "approval unknown";
+  const readOnly = toolSlugTokens(toolSlug).find((token) =>
+    READ_ONLY_TOOL_ACTIONS.has(token),
+  );
+  return readOnly ? `read-only (${readOnly})` : "approval likely";
+}
+
+function compactConnection(connection: JsonRecord) {
+  return {
+    toolkit: stringField(connection, "toolkit") ?? "unknown",
+    status: stringField(connection, "status") ?? "unknown",
+    connectedAccountId:
+      stringField(connection, "connectedAccountId", "connected_account_id") ??
+      stringField(connection, "id"),
+    accountLabel:
+      stringField(connection, "accountLabel", "account_label", "label") ?? null,
+  };
+}
+
+function summarizeConnectedApps(value: unknown) {
+  const record = asRecord(value);
+  const connections = asRecordArray(record?.connections).map(compactConnection);
+  return {
+    available: true,
+    count: connections.length,
+    connections,
+  };
+}
+
+function workspaceSlugFromContext(context: JsonRecord) {
+  const workspace = asRecord(context.workspace);
+  return (
+    stringField(workspace, "slug") ?? stringField(context, "workspaceSlug")
+  );
+}
+
+function workspaceUrls(host: string, workspaceSlug: string | undefined) {
+  if (!workspaceSlug) return {};
+  const base = normalizeHost(host);
+  return {
+    dashboardUrl: `${base}/${workspaceSlug}`,
+    approvalsUrl: `${base}/${workspaceSlug}/approvals`,
+  };
+}
+
+function nextContextCommands() {
+  return [
+    "dench onboard --json",
+    "dench tasks --json",
+    'dench log "Brief progress update"',
+    'dench tool search "what you need" --toolkit <app>',
+    'dench approval request "Risky action to approve"',
+  ];
+}
+
+async function connectedAppsContext(runtime: Runtime) {
+  if (runtime.mode !== "session") {
+    return {
+      available: false,
+      reason: "Connected apps require a logged-in Dench agent session.",
+      count: 0,
+      connections: [],
+    };
+  }
+
+  try {
+    return summarizeConnectedApps(
+      await runtime.client.action(
+        api.functions.agentToolsNode.agentToolStatus,
+        {
+          sessionToken: runtime.sessionToken,
+        },
+      ),
+    );
+  } catch (error) {
+    const unavailable = toolGatewayUnavailable(error);
+    if (unavailable) {
+      return {
+        ...unavailable,
+        count: 0,
+        connections: [],
+      };
+    }
+    return {
+      available: false,
+      error: errorMessage(error),
+      count: 0,
+      connections: [],
+    };
+  }
+}
+
+async function buildContext(runtime: Runtime) {
+  const mine =
+    runtime.mode === "session"
+      ? ((await runtime.client.query(
+          api.functions.agentWorkspace.whatCanIDoHere,
+          {
+            sessionToken: runtime.sessionToken,
+          },
+        )) as JsonRecord)
+      : summarizeDevMine(
+          runtime.workspaceArgs.workspaceSlug,
+          await devOverview(runtime),
+        );
+
+  const urls =
+    runtime.mode === "session"
+      ? workspaceUrls(runtime.host, workspaceSlugFromContext(mine))
+      : {};
+
+  return {
+    ...mine,
+    ...urls,
+    connectedApps: await connectedAppsContext(runtime),
+    nextCommands: nextContextCommands(),
+  };
+}
+
+async function runOnboarding() {
+  let runtime: Runtime;
+  try {
+    runtime = await getRuntime();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const isLoginRequired =
+      error instanceof CliError && error.payload.code === "login_required";
+    if (!isLoginRequired && !message.includes("Not logged in")) {
+      throw error;
+    }
+    logHuman("No Dench session found. Starting login first.");
+    await login();
+    runtime = await getRuntime();
+  }
+
+  const context = await buildContext(runtime);
+  print(
+    json
+      ? { ok: true, context }
+      : [
+          "Dench onboarding complete.",
+          "",
+          formatContext(context),
+          "",
+          "Setup is complete when the workspace and agent above are correct.",
+        ].join("\n"),
+  );
+}
+
+function formatCount(value: unknown) {
+  return typeof value === "number" ? String(value) : "0";
+}
+
+function agentDisplayName(agent: JsonRecord | undefined) {
+  return (
+    stringField(agent, "name") ??
+    stringField(agent, "slug") ??
+    stringField(agent, "id") ??
+    stringField(agent, "_id") ??
+    "unknown agent"
+  );
+}
+
+function formatContext(context: JsonRecord) {
+  const counts = asRecord(context.counts);
+  const agent = asRecord(context.agent);
+  const workspace = asRecord(context.workspace);
+  const connectedApps = asRecord(context.connectedApps);
+  const connections = asRecordArray(connectedApps?.connections);
+  const tasksRecord = asRecord(context.tasks);
+  const tasks =
+    asRecordArray(tasksRecord?.assignedToMe).length > 0 ||
+    asRecordArray(tasksRecord?.open).length > 0
+      ? [
+          ...asRecordArray(tasksRecord?.assignedToMe),
+          ...asRecordArray(tasksRecord?.open),
+        ]
+      : asRecordArray(context.tasks);
+  const approvals = asRecordArray(context.pendingApprovals);
+  const suggestedWork = asRecordArray(context.suggestedWork);
+  const memories = asRecordArray(context.memory);
+  const nextActions = Array.isArray(context.nextActions)
+    ? context.nextActions.filter(
+        (item): item is string => typeof item === "string",
+      )
+    : [];
+  const lines = [
+    "Dench context",
+    `Workspace: ${
+      stringField(workspace, "name") ??
+      stringField(context, "workspace") ??
+      "unknown"
+    }${
+      (stringField(workspace, "slug") ?? stringField(context, "workspaceSlug"))
+        ? ` (${stringField(workspace, "slug") ?? stringField(context, "workspaceSlug")})`
+        : ""
+    }`,
+    `Agent: ${agentDisplayName(agent)}${
+      stringField(agent, "kind") ? ` [${stringField(agent, "kind")}]` : ""
+    }`,
+    `Counts: ${formatCount(counts?.tasks ?? tasks.length)} visible tasks, ${formatCount(
+      counts?.myAssignedTasks ??
+        asRecordArray(tasksRecord?.assignedToMe).length,
+    )} assigned to me, ${formatCount(
+      counts?.myPendingApprovals ?? approvals.length,
+    )} pending approvals`,
+  ];
+
+  const dashboardUrl = stringField(context, "dashboardUrl");
+  const approvalsUrl = stringField(context, "approvalsUrl");
+  if (dashboardUrl || approvalsUrl) {
+    lines.push(
+      `Dashboard: ${dashboardUrl ?? "unknown"}`,
+      `Approvals: ${approvalsUrl ?? "unknown"}`,
+    );
+  }
+
+  lines.push("", "Assigned tasks:");
+
+  if (tasks.length === 0) {
+    lines.push("  none");
+  } else {
+    lines.push(
+      ...tasks
+        .slice(0, 5)
+        .map(
+          (task) =>
+            `  - ${stringField(task, "title") ?? stringField(task, "id") ?? "untitled"} [${stringField(task, "status") ?? "unknown"}]`,
+        ),
+    );
+  }
+
+  lines.push("", "Pending approvals requested by me:");
+  if (approvals.length === 0) {
+    lines.push("  none");
+  } else {
+    lines.push(
+      ...approvals
+        .slice(0, 5)
+        .map(
+          (approval) =>
+            `  - ${stringField(approval, "title") ?? stringField(approval, "id") ?? "untitled"} [${stringField(approval, "risk") ?? "unknown"}]`,
+        ),
+    );
+  }
+
+  lines.push("", "Connected apps:");
+  if (connectedApps?.available === false) {
+    lines.push(
+      `  unavailable: ${
+        stringField(connectedApps, "error", "reason") ?? "could not check apps"
+      }`,
+    );
+  } else if (connections.length === 0) {
+    lines.push("  none");
+  } else {
+    lines.push(
+      ...connections
+        .slice(0, 8)
+        .map(
+          (connection) =>
+            `  - ${stringField(connection, "toolkit") ?? "unknown"} [${stringField(connection, "status") ?? "unknown"}]${
+              stringField(connection, "accountLabel")
+                ? ` ${stringField(connection, "accountLabel")}`
+                : ""
+            }`,
+        ),
+    );
+  }
+
+  lines.push("", "Suggested work:");
+  if (suggestedWork.length === 0) {
+    lines.push("  none");
+  } else {
+    lines.push(
+      ...suggestedWork
+        .slice(0, 5)
+        .map(
+          (item) =>
+            `  - ${stringField(item, "title") ?? stringField(item, "id") ?? "untitled"}`,
+        ),
+    );
+  }
+
+  lines.push("", "Memory:");
+  if (memories.length === 0) {
+    lines.push("  none");
+  } else {
+    lines.push(
+      ...memories
+        .slice(0, 5)
+        .map(
+          (memory) =>
+            `  - ${stringField(memory, "key") ?? "memory"}: ${compactLine(stringField(memory, "text"), 100) ?? ""}`,
+        ),
+    );
+  }
+
+  if (nextActions.length > 0) {
+    lines.push(
+      "",
+      "Next actions:",
+      ...nextActions.map((action) => `  - ${action}`),
+    );
+  }
+
+  lines.push("", "Useful next commands:");
+  lines.push(
+    ...nextContextCommands().map((command) => `  - ${command}`),
+    "",
+    "Use --json for structured output.",
+  );
+  return lines.join("\n");
+}
+
+function toolkitSlugFromTool(tool: JsonRecord) {
+  const toolkit = tool.toolkit;
+  if (typeof toolkit === "string") return toolkit;
+  const toolkitRecord = asRecord(toolkit);
+  return (
+    stringField(toolkitRecord, "slug", "name") ??
+    stringField(tool, "toolkit_slug")
+  );
+}
+
+function connectedToolkitSet(data: JsonRecord | undefined) {
+  const connected = new Set<string>();
+  const connectedToolkits = Array.isArray(data?.connected_toolkits)
+    ? data?.connected_toolkits
+    : [];
+  for (const toolkit of connectedToolkits) {
+    const value = stringValue(toolkit);
+    if (value) connected.add(value.toLowerCase());
+  }
+  for (const status of asRecordArray(data?.toolkit_connection_statuses)) {
+    const toolkit = stringField(status, "toolkit");
+    const isConnected = booleanField(status, "has_active_connection");
+    if (toolkit && isConnected) connected.add(toolkit.toLowerCase());
+  }
+  return connected;
+}
+
+function searchToolItems(searchResult: unknown) {
+  const root = asRecord(searchResult);
+  const data = asRecord(root?.data) ?? root;
+  const directItems = asRecordArray(data?.items);
+  if (directItems.length > 0) {
+    return { data, items: directItems };
+  }
+
+  const schemas = asRecord(data?.tool_schemas);
+  if (!schemas) return { data, items: [] };
+  return {
+    data,
+    items: Object.entries(schemas).flatMap<JsonRecord>(([slug, value]) => {
+      const tool = asRecord(value);
+      return tool
+        ? [{ ...tool, tool_slug: stringField(tool, "tool_slug") ?? slug }]
+        : [];
+    }),
+  };
+}
+
+function compactToolSearchResult(searchResult: unknown) {
+  const root = asRecord(searchResult);
+  const { data, items } = searchToolItems(searchResult);
+  const connected = connectedToolkitSet(data);
+  const tools = items.map((tool) => {
+    const toolkit = toolkitSlugFromTool(tool);
+    const connectionStatus = asRecord(tool.connection_status);
+    const isConnected =
+      booleanField(connectionStatus, "is_connected") ??
+      (toolkit ? connected.has(toolkit.toLowerCase()) : undefined);
+    const slug = stringField(tool, "slug", "tool_slug") ?? "unknown_tool";
+    return {
+      slug,
+      name: stringField(tool, "display_name", "name") ?? slug,
+      toolkit: toolkit ?? "unknown",
+      approval: toolApprovalHint(slug),
+      connected:
+        isConnected === undefined
+          ? "connection unknown"
+          : isConnected
+            ? "connected"
+            : "not connected",
+      description: compactLine(tool.description) ?? null,
+    };
+  });
+
+  return {
+    ok: root?.ok ?? true,
+    query: stringField(root, "query") ?? stringField(data, "query") ?? null,
+    returned: tools.length,
+    total:
+      numberField(data, "total_items", "total", "count") ??
+      numberField(root, "total_items", "total", "count") ??
+      tools.length,
+    tools,
+  };
+}
+
+function formatToolSearchResult(searchResult: unknown) {
+  const summary = compactToolSearchResult(searchResult);
+  const query = summary.query ? ` for "${summary.query}"` : "";
+  if (summary.tools.length === 0) {
+    return `No matching tools found${query}.\nUse --json if you need the raw provider response.`;
+  }
+
+  const lines = [`Top tools${query}:`];
+  for (const [index, tool] of summary.tools.entries()) {
+    lines.push(
+      `${index + 1}. ${tool.slug} - ${tool.name}`,
+      `   toolkit: ${tool.toolkit} | ${tool.approval} | ${tool.connected}`,
+    );
+    if (tool.description) {
+      lines.push(`   ${tool.description}`);
+    }
+  }
+  lines.push(
+    "",
+    "Use dench tool run <slug> --args '{...}' when ready.",
+    "Use --json only when you need full schemas or raw arguments.",
+  );
+  return lines.join("\n");
+}
+
+function printToolSearchResult(searchResult: unknown) {
+  print(json ? searchResult : formatToolSearchResult(searchResult));
+}
+
+const SENSITIVE_KEY_RE =
+  /(?:otp|oneTime|verification|security|passcode|password|secret|api[_-]?key|access[_-]?token|refresh[_-]?token|authorization)/i;
+
+function redactSensitiveString(value: string) {
+  return value
+    .replace(
+      /\b((?:one[-\s]?time|verification|security|login|sign[-\s]?in|auth(?:entication)?|2fa|mfa|otp|passcode|code)[^.\n\r]{0,80}?)(\d[\d\s-]{2,10}\d)\b/gi,
+      "$1[redacted-code]",
+    )
+    .replace(
+      /\b((?:api[_\s-]?key|secret|token|password)[^.\n\r]{0,60}?)([A-Za-z0-9_=-]{12,})\b/gi,
+      "$1[redacted-secret]",
+    );
+}
+
+function redactSensitiveDisplay(value: unknown, key?: string): unknown {
+  if (typeof value === "string") {
+    return key && SENSITIVE_KEY_RE.test(key)
+      ? "[redacted]"
+      : redactSensitiveString(value);
+  }
+  if (typeof value === "number" && key && SENSITIVE_KEY_RE.test(key)) {
+    return "[redacted]";
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSensitiveDisplay(item));
+  }
+  const record = asRecord(value);
+  if (!record) return value;
+
+  return Object.fromEntries(
+    Object.entries(record).map(([entryKey, entryValue]) => [
+      entryKey,
+      redactSensitiveDisplay(entryValue, entryKey),
+    ]),
+  );
+}
+
+function connectionUrlFromToolConnect(result: unknown) {
+  const record = asRecord(result);
+  const data = asRecord(record?.data);
+  return (
+    stringField(record, "connectUrl", "redirect_url", "redirectUrl", "url") ??
+    stringField(data, "redirect_url", "redirectUrl", "url")
+  );
+}
+
+function withToolConnectSummary(result: unknown) {
+  const record = asRecord(result);
+  if (!record) return result;
+  const toolkit = stringField(record, "toolkit") ?? "app";
+  const connectUrl = connectionUrlFromToolConnect(record);
+  if (!connectUrl) return record;
+  return {
+    ...record,
+    connectUrl,
+    linkText: `Connect ${toolkit} here`,
+    message: `Connect ${toolkit} here: ${connectUrl}`,
+  };
+}
+
+function formatToolConnectResult(result: unknown) {
+  const record = asRecord(withToolConnectSummary(result));
+  if (!record) return String(result);
+  const toolkit = stringField(record, "toolkit") ?? "app";
+  const connectUrl = stringField(record, "connectUrl");
+  if (connectUrl) {
+    return `Connect ${toolkit} here: ${connectUrl}`;
+  }
+  return JSON.stringify(record, null, 2);
+}
+
+function withToolRunGuidance(runtime: Runtime, result: unknown) {
+  const record = asRecord(result);
+  if (!record || record.requiresApproval !== true) return result;
+  const approvalId = stringField(record, "approvalId");
+  const statusContext =
+    runtime.mode === "session"
+      ? workspaceUrls(runtime.host, runtime.organization?.slug)
+      : {};
+  const approvalCommand = approvalId
+    ? `dench approval approve ${approvalId} --evidence "User said yes in chat" --json`
+    : undefined;
+  return {
+    ...record,
+    ...statusContext,
+    ...(approvalCommand ? { approvalCommand } : {}),
+    nextActions: [
+      "Ask the human for an explicit yes/no in chat.",
+      ...(approvalCommand ? [`If yes, run: ${approvalCommand}`] : []),
+      approvalId
+        ? `Rerun the exact same dench tool run command with --approval ${approvalId}.`
+        : "Rerun the exact same dench tool run command after approval.",
+    ],
+  };
+}
+
+function printToolRunResult(runtime: Runtime, result: unknown) {
+  const guided = withToolRunGuidance(runtime, result);
+  print(json ? guided : redactSensitiveDisplay(guided));
+}
+
+async function devOverview(runtime: Awaited<ReturnType<typeof getRuntime>>) {
+  if (runtime.mode !== "dev") {
+    throw new Error("Not in dev mode");
+  }
+  return (await runtime.client.query(
+    api.functions.agentWorkspace.devListWorkspaceOverview,
+    runtime.workspaceArgs,
+  )) as WorkspaceOverview;
+}
+
+function summarizeDevOverview(workspaceSlug: string, data: WorkspaceOverview) {
+  return {
+    workspace: workspaceSlug,
+    agents: data.agents.length,
+    projects: data.projects.length,
+    tasks: data.tasks.length,
+    approvals: data.approvals.filter(
+      (approval) => approval.status === "pending",
+    ).length,
+    rules: data.rules.length,
+  };
+}
+
+function compactTask(task: JsonRecord) {
+  return {
+    id: task._id ?? task.id,
+    title: task.title,
+    status: task.status,
+    priority: task.priority,
+    risk: task.risk,
+    assignedAgentId: task.assignedAgentId,
+  };
+}
+
+function compactApproval(approval: JsonRecord) {
+  return {
+    id: approval.id ?? approval._id,
+    title: approval.title,
+    risk: approval.risk,
+    status: approval.status,
+    taskId: approval.taskId,
+    createdAt: approval.createdAt,
+  };
+}
+
+function summarizeAgentStatus(
+  status: AgentStatus,
+  tasks: JsonRecord[],
+  host?: string,
+) {
+  const agentId = status.agent?.id;
+  const assignedTasks = agentId
+    ? tasks.filter((task) => task.assignedAgentId === agentId)
+    : [];
+  const pendingApprovals = (status.approvals ?? []).filter(
+    (approval) => approval.status === "pending" && approval.agentId === agentId,
+  );
+  const urls = host ? workspaceUrls(host, status.workspaceSlug) : {};
+
+  return {
+    workspace: status.workspace,
+    workspaceSlug: status.workspaceSlug,
+    ...urls,
+    agent: status.agent,
+    counts: {
+      ...(status.counts ?? {}),
+      myAssignedTasks: assignedTasks.length,
+      myPendingApprovals: pendingApprovals.length,
+    },
+    rules: status.rules ?? [],
+    tasks: assignedTasks.map(compactTask),
+    pendingApprovals: pendingApprovals.map(compactApproval),
+  };
+}
+
+function summarizeDevMine(workspaceSlug: string, data: WorkspaceOverview) {
+  const agentId = option("--agent") ?? data.agents[0]?._id;
+  const agent = data.agents.find((item) => item._id === agentId) ?? null;
+  const tasks = data.tasks.filter((task) => task.assignedAgentId === agentId);
+  const pendingApprovals = data.approvals.filter(
+    (approval) => approval.status === "pending" && approval.agentId === agentId,
+  );
+
+  return {
+    workspace: workspaceSlug,
+    agent,
+    counts: {
+      agents: data.agents.length,
+      projects: data.projects.length,
+      tasks: data.tasks.length,
+      pendingApprovals: data.approvals.filter(
+        (approval) => approval.status === "pending",
+      ).length,
+      rules: data.rules.length,
+      myAssignedTasks: tasks.length,
+      myPendingApprovals: pendingApprovals.length,
+    },
+    rules: data.rules,
+    tasks: tasks.map(compactTask),
+    pendingApprovals: pendingApprovals.map(compactApproval),
+  };
+}
+
+async function defaultDevAgentId(
+  runtime: Awaited<ReturnType<typeof getRuntime>>,
+) {
+  const data = await devOverview(runtime);
+  const agent = data.agents[0];
+  if (!agent) {
+    throw new Error(
+      'No agent registered yet. Run: dench register --name "AI Agent" --kind other --dev',
+    );
+  }
+  return agent._id;
+}
+
+async function listArtifacts(runtime: Runtime, limit?: number) {
+  if (runtime.mode === "session") {
+    try {
+      return (await runtime.client.query(
+        api.functions.agentWorkspace.agentListArtifacts,
+        {
+          sessionToken: runtime.sessionToken,
+          limit,
+        },
+      )) as JsonRecord[];
+    } catch (error) {
+      if (!isMissingConvexFunction(error)) throw error;
+      const context = await buildContext(runtime);
+      return asRecordArray(asRecord(context)?.recentArtifacts).slice(
+        0,
+        limit ?? 25,
+      );
+    }
+  }
+  const data = await devOverview(runtime);
+  return asRecordArray(data.recentArtifacts);
+}
+
+async function listSuggestedWork(runtime: Runtime) {
+  if (runtime.mode === "session") {
+    const context = await buildContext(runtime);
+    return asRecordArray(asRecord(context)?.suggestedWork);
+  }
+  return suggestedWorkFromArtifacts(await listArtifacts(runtime, 50));
+}
+
+function suggestedWorkFromArtifacts(artifacts: JsonRecord[]) {
+  return artifacts.filter(
+    (artifact) =>
+      stringField(artifact, "type") === "task_suggestion" &&
+      stringField(artifact, "status") === "draft",
+  );
+}
+
+async function runFsCommand() {
+  const subArgs = args.slice(args.indexOf("fs") + 1);
+  const configuredBinary = process.env.DENCH_FS_DAEMON_BIN?.trim();
+  const binary = configuredBinary || "dench-fs-daemon";
+  let exitCode: number;
+  try {
+    exitCode = await spawnInherited(binary, subArgs);
+  } catch (error) {
+    if (configuredBinary || !isCommandNotFound(error)) {
+      throw error;
+    }
+    const localDaemon = fileURLToPath(
+      new URL("./fs-daemon.ts", import.meta.url),
+    );
+    exitCode = await spawnInherited("bun", [localDaemon, ...subArgs]);
+  }
+  if (exitCode !== 0) {
+    process.exitCode = exitCode;
+  }
+}
+
+async function spawnInherited(binary: string, commandArgs: string[]) {
+  return await new Promise<number>((resolve, reject) => {
+    const child = spawn(binary, commandArgs, {
+      stdio: "inherit",
+      env: process.env,
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+function isCommandNotFound(error: unknown) {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+async function main() {
+  const command = positional(0);
+  const subcommand = positional(1);
+
+  if (command === "version" || hasFlag("--version")) {
+    console.log(await cliVersion());
+    return;
+  }
+
+  if (!command || command === "help") {
+    help();
+    return;
+  }
+
+  if (
+    command === "tool" &&
+    (!subcommand || subcommand === "help" || hasFlag("--help"))
+  ) {
+    toolHelp();
+    return;
+  }
+
+  if (command === "apps" && (subcommand === "help" || hasFlag("--help"))) {
+    appsHelp();
+    return;
+  }
+
+  if (
+    command === "billing" &&
+    (!subcommand || subcommand === "help" || hasFlag("--help"))
+  ) {
+    billingHelp();
+    return;
+  }
+
+  if (command === "login" && hasFlag("--help")) {
+    loginHelp();
+    return;
+  }
+
+  if (
+    (command === "onboard" ||
+      command === "setup" ||
+      command === "what-can-i-do") &&
+    (subcommand === "help" || hasFlag("--help"))
+  ) {
+    onboardHelp();
+    return;
+  }
+
+  if (command === "context" && hasFlag("--help")) {
+    contextHelp();
+    return;
+  }
+
+  if (
+    command === "memory" &&
+    (!subcommand || subcommand === "help" || hasFlag("--help"))
+  ) {
+    memoryHelp();
+    return;
+  }
+
+  if (
+    (command === "artifacts" || command === "suggested-work") &&
+    (subcommand === "help" || hasFlag("--help"))
+  ) {
+    artifactsHelp();
+    return;
+  }
+
+  if (command === "status" && hasFlag("--help")) {
+    statusHelp();
+    return;
+  }
+
+  if (command === "tasks" && hasFlag("--help")) {
+    tasksHelp();
+    return;
+  }
+
+  if (command === "logout" && hasFlag("--help")) {
+    logoutHelp();
+    return;
+  }
+
+  if (command === "autonomous") {
+    if (!subcommand || subcommand === "help" || hasFlag("--help")) {
+      autonomousHelp();
+      return;
+    }
+    if (subcommand === "run") {
+      await startAutonomousRun();
+      return;
+    }
+    throw new Error(`Unknown autonomous command: ${filteredArgs.join(" ")}`);
+  }
+
+  if (command === "crm") {
+    const subArgs = 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
+    // subcommand list inline.
+    if (!sub || sub === "help" || sub === "--help") {
+      const { runCrmCommand } = await import("./crm");
+      // runCrmCommand only needs `convex` for actual queries; help
+      // doesn't touch it. Pass a minimal stub.
+      // biome-ignore lint/suspicious/noExplicitAny: harmless help-only stub
+      await runCrmCommand({ convex: {} as any, args: subArgs });
+      return;
+    }
+    const { runCrmCommand } = await import("./crm");
+    const runtime = await getRuntime();
+    const sessionRuntime = requireSessionRuntime(runtime, "dench crm");
+    await runCrmCommand({
+      convex: sessionRuntime.client,
+      args: subArgs,
+      // Server-side `requireCrmAccess` (convex/lib/crm/access.ts) accepts
+      // this token and resolves the agent's organization without a Convex
+      // Auth cookie. Mirrors the pattern used by every agentWorkspace fn.
+      sessionToken: sessionRuntime.sessionToken,
+    });
+    return;
+  }
+
+  if (command === "fs") {
+    await runFsCommand();
+    return;
+  }
+
+  if (command === "agent") {
+    const subArgs = args.slice(args.indexOf("agent") + 1);
+    const sub = subArgs[0];
+    if (!sub || sub === "help" || sub === "--help") {
+      const { runAgentCommand } = await import("./agent");
+      // biome-ignore lint/suspicious/noExplicitAny: harmless help-only stub
+      await runAgentCommand({ convex: {} as any, args: subArgs });
+      return;
+    }
+    const { runAgentCommand } = await import("./agent");
+    const runtime = await getRuntime();
+    await runAgentCommand({
+      convex: runtime.client,
+      args: subArgs,
+    });
+    return;
+  }
+
+  if (command === "login") {
+    await login();
+    return;
+  }
+
+  if (
+    command === "onboard" ||
+    command === "setup" ||
+    command === "what-can-i-do"
+  ) {
+    await runOnboarding();
+    return;
+  }
+
+  if (command === "sessions") {
+    await listSessions();
+    return;
+  }
+
+  if (command === "use") {
+    await selectSession();
+    return;
+  }
+
+  if (command === "logout") {
+    await logout();
+    return;
+  }
+
+  const runtime = await getRuntime();
+
+  if (command === "billing") {
+    if (subcommand === "status") {
+      await billingStatus(runtime);
+      return;
+    }
+    if (subcommand === "topup") {
+      await billingTopup(runtime);
+      return;
+    }
+    billingHelp();
+    return;
+  }
+
+  if (command === "apps") {
+    await printToolStatus(runtime);
+    return;
+  }
+
+  if (command === "context") {
+    const context = await buildContext(runtime);
+    print(json ? context : formatContext(context));
+    return;
+  }
+
+  if (command === "memory") {
+    const sessionRuntime = requireSessionRuntime(runtime, "dench memory");
+    if (subcommand === "search") {
+      const query = positionalsFrom(2).join(" ").trim();
+      if (!query) throw new Error('Usage: dench memory search "query"');
+      print(
+        await sessionRuntime.client.query(
+          api.functions.agentWorkspace.agentSearchMemory,
+          {
+            sessionToken: sessionRuntime.sessionToken,
+            query,
+            limit: parseNumberOption("--limit"),
+          },
+        ),
+      );
+      return;
+    }
+    if (subcommand === "save") {
+      const key = positional(2);
+      const text = positionalsFrom(3).join(" ").trim();
+      if (!key || !text) {
+        throw new Error('Usage: dench memory save <key> "text"');
+      }
+      print(
+        await sessionRuntime.client.mutation(
+          api.functions.agentWorkspace.agentSaveMemory,
+          {
+            sessionToken: sessionRuntime.sessionToken,
+            key,
+            kind: (option("--kind") ?? "fact") as never,
+            text,
+            tags: parseCommaOption("--tags"),
+            sensitivity: (option("--sensitivity") ?? "normal") as never,
+          },
+        ),
+      );
+      return;
+    }
+    throw new Error(`Unknown memory command: ${filteredArgs.join(" ")}`);
+  }
+
+  if (command === "artifacts") {
+    print(await listArtifacts(runtime, parseNumberOption("--limit")));
+    return;
+  }
+
+  if (command === "suggested-work") {
+    if (subcommand === "task") {
+      const sessionRuntime = requireSessionRuntime(
+        runtime,
+        "dench suggested-work task",
+      );
+      const artifactId = positional(2);
+      if (!artifactId) {
+        throw new Error("Usage: dench suggested-work task <artifactId>");
+      }
+      print(
+        await sessionRuntime.client
+          .mutation(api.functions.agentWorkspace.agentConvertSuggestionToTask, {
+            sessionToken: sessionRuntime.sessionToken,
+            artifactId: artifactId as never,
+          })
+          .catch(async (error) => {
+            if (!isMissingConvexFunction(error)) throw error;
+            const suggestion = (await listSuggestedWork(runtime)).find(
+              (item) => stringField(item, "id") === artifactId,
+            );
+            if (!suggestion) throw error;
+            const title = stringField(suggestion, "title") ?? "Suggested work";
+            const created = (await sessionRuntime.client.mutation(
+              api.functions.agentWorkspace.agentCreateTask,
+              {
+                sessionToken: sessionRuntime.sessionToken,
+                title,
+                description: stringField(suggestion, "content"),
+                priority: "medium",
+                risk: "medium",
+              },
+            )) as JsonRecord;
+            return {
+              ok: true,
+              fallback: true,
+              artifactId,
+              title,
+              taskId: created.taskId,
+              note: "Created a task from suggested work. Artifact status will update after the backend conversion function is deployed.",
+            };
+          }),
+      );
+      return;
+    }
+    print(await listSuggestedWork(runtime));
+    return;
+  }
+
+  if (command === "status") {
+    if (runtime.mode === "session") {
+      const status = (await runtime.client.query(
+        api.functions.agentWorkspace.agentStatus,
+        {
+          sessionToken: runtime.sessionToken,
+        },
+      )) as AgentStatus;
+      if (scopedStatus) {
+        const tasks = (await runtime.client.query(
+          api.functions.agentWorkspace.agentListTasks,
+          {
+            sessionToken: runtime.sessionToken,
+          },
+        )) as JsonRecord[];
+        print(summarizeAgentStatus(status, tasks, runtime.host));
+        return;
+      }
+      print(status);
+      return;
+    }
+    const data = await devOverview(runtime);
+    const output = scopedStatus
+      ? summarizeDevMine(runtime.workspaceArgs.workspaceSlug, data)
+      : json
+        ? data
+        : summarizeDevOverview(runtime.workspaceArgs.workspaceSlug, data);
+    print(output);
+    return;
+  }
+
+  if (command === "tasks") {
+    if (runtime.mode === "session") {
+      print(
+        await runtime.client.query(
+          api.functions.agentWorkspace.agentListTasks,
+          {
+            sessionToken: runtime.sessionToken,
+          },
+        ),
+      );
+      return;
+    }
+    const data = await devOverview(runtime);
+    print(data.tasks);
+    return;
+  }
+
+  if (command === "agents") {
+    if (runtime.mode === "session") {
+      const status = await runtime.client.query(
+        api.functions.agentWorkspace.agentStatus,
+        {
+          sessionToken: runtime.sessionToken,
+        },
+      );
+      print(status.agents);
+      return;
+    }
+    const data = await devOverview(runtime);
+    print(data.agents);
+    return;
+  }
+
+  if (command === "approvals") {
+    if (runtime.mode === "session") {
+      const status = await runtime.client.query(
+        api.functions.agentWorkspace.agentStatus,
+        {
+          sessionToken: runtime.sessionToken,
+        },
+      );
+      print(status.approvals);
+      return;
+    }
+    const data = await devOverview(runtime);
+    print(data.approvals);
+    return;
+  }
+
+  if (command === "register") {
+    if (runtime.mode !== "dev") {
+      throw new Error(
+        "register is only needed in dev mode. Real sessions use dench login.",
+      );
+    }
+    const agentId = await runtime.client.mutation(
+      api.functions.agentWorkspace.devRegisterAgent,
+      {
+        ...runtime.workspaceArgs,
+        name: option("--name") ?? "AI Agent",
+        kind: normalizeAgentKind(option("--kind")),
+      },
+    );
+    print({ ok: true, agentId });
+    return;
+  }
+
+  if (command === "project" && subcommand === "create") {
+    if (runtime.mode !== "dev") {
+      throw new Error(
+        "project create is not available for agent sessions yet.",
+      );
+    }
+    const name = positional(2);
+    if (!name) throw new Error("Missing project name");
+    const projectId = await runtime.client.mutation(
+      api.functions.agentWorkspace.devCreateProject,
+      {
+        ...runtime.workspaceArgs,
+        name,
+        repositoryUrl: option("--repo"),
+        rootPath: option("--root"),
+      },
+    );
+    print({ ok: true, projectId });
+    return;
+  }
+
+  if (command === "task" && subcommand === "create") {
+    const title = positional(2);
+    if (!title) throw new Error("Missing task title");
+    const taskArgs = {
+      title,
+      description: option("--description"),
+      priority: (option("--priority") ?? "medium") as "low" | "medium" | "high",
+      risk: (option("--risk") ?? "medium") as "low" | "medium" | "high",
+    };
+    if (runtime.mode === "session") {
+      print(
+        await runtime.client.mutation(
+          api.functions.agentWorkspace.agentCreateTask,
+          {
+            sessionToken: runtime.sessionToken,
+            ...taskArgs,
+          },
+        ),
+      );
+      return;
+    }
+    const taskId = await runtime.client.mutation(
+      api.functions.agentWorkspace.devCreateTask,
+      {
+        ...runtime.workspaceArgs,
+        ...taskArgs,
+      },
+    );
+    print({ ok: true, taskId });
+    return;
+  }
+
+  if (command === "task" && subcommand === "status") {
+    const sessionRuntime = requireSessionRuntime(runtime, "dench task status");
+    const taskId = positional(2);
+    const status = positional(3);
+    if (!taskId || !status) {
+      throw new Error("Usage: dench task status <taskId> <status>");
+    }
+    print(
+      await sessionRuntime.client.mutation(
+        api.functions.agentWorkspace.agentUpdateTaskStatus,
+        {
+          sessionToken: sessionRuntime.sessionToken,
+          taskId: taskId as never,
+          status: status as never,
+          note: option("--note"),
+        },
+      ),
+    );
+    return;
+  }
+
+  if (
+    command === "task" &&
+    (subcommand === "comment" ||
+      subcommand === "handoff" ||
+      subcommand === "block")
+  ) {
+    const sessionRuntime = requireSessionRuntime(
+      runtime,
+      `dench task ${subcommand}`,
+    );
+    const taskId = positional(2);
+    const body = positionalsFrom(3).join(" ").trim();
+    if (!taskId || !body) {
+      throw new Error(`Usage: dench task ${subcommand} <taskId> "message"`);
+    }
+    print(
+      await sessionRuntime.client.mutation(
+        api.functions.agentWorkspace.agentAddTaskComment,
+        {
+          sessionToken: sessionRuntime.sessionToken,
+          taskId: taskId as never,
+          kind:
+            subcommand === "handoff"
+              ? "handoff"
+              : subcommand === "block"
+                ? "blocker"
+                : "comment",
+          body,
+          targetAgentId: option("--agent") as never,
+        },
+      ),
+    );
+    return;
+  }
+
+  if (command === "task" && subcommand === "depends-on") {
+    const sessionRuntime = requireSessionRuntime(
+      runtime,
+      "dench task depends-on",
+    );
+    const taskId = positional(2);
+    const dependsOnTaskId = positional(3);
+    if (!taskId || !dependsOnTaskId) {
+      throw new Error(
+        "Usage: dench task depends-on <taskId> <dependsOnTaskId>",
+      );
+    }
+    print(
+      await sessionRuntime.client.mutation(
+        api.functions.agentWorkspace.agentAddTaskDependency,
+        {
+          sessionToken: sessionRuntime.sessionToken,
+          taskId: taskId as never,
+          dependsOnTaskId: dependsOnTaskId as never,
+          note: option("--note"),
+        },
+      ),
+    );
+    return;
+  }
+
+  if (command === "claim") {
+    const taskId = positional(1);
+    if (!taskId) throw new Error("Missing task id");
+    if (runtime.mode === "session") {
+      print(
+        await runtime.client.mutation(
+          api.functions.agentWorkspace.agentClaimTask,
+          {
+            sessionToken: runtime.sessionToken,
+            taskId: taskId as never,
+          },
+        ),
+      );
+      return;
+    }
+    const agentId = option("--agent") ?? (await defaultDevAgentId(runtime));
+    print(
+      await runtime.client.mutation(api.functions.agentWorkspace.devClaimTask, {
+        ...runtime.workspaceArgs,
+        taskId: taskId as never,
+        agentId: agentId as never,
+      }),
+    );
+    return;
+  }
+
+  if (command === "log") {
+    const message = positional(1);
+    if (!message) throw new Error("Missing log message");
+    if (runtime.mode === "session") {
+      print(
+        await runtime.client.mutation(
+          api.functions.agentWorkspace.agentAppendLog,
+          {
+            sessionToken: runtime.sessionToken,
+            message,
+            taskId: option("--task") as never,
+          },
+        ),
+      );
+      return;
+    }
+    print(
+      await runtime.client.mutation(api.functions.agentWorkspace.devAppendLog, {
+        ...runtime.workspaceArgs,
+        message,
+        agentId: option("--agent") as never,
+        taskId: option("--task") as never,
+      }),
+    );
+    return;
+  }
+
+  if (command === "approval" && subcommand === "request") {
+    const title = positional(2);
+    if (!title) throw new Error("Missing approval title");
+    if (runtime.mode === "session") {
+      print(
+        await runtime.client.mutation(
+          api.functions.agentWorkspace.agentRequestApproval,
+          {
+            sessionToken: runtime.sessionToken,
+            title,
+            reason: option("--reason"),
+            risk: (option("--risk") ?? "high") as "low" | "medium" | "high",
+            taskId: option("--task") as never,
+          },
+        ),
+      );
+      return;
+    }
+    const approvalId = await runtime.client.mutation(
+      api.functions.agentWorkspace.devRequestApproval,
+      {
+        ...runtime.workspaceArgs,
+        title,
+        reason:
+          option("--reason") ??
+          "Agent requests human approval before a risky action.",
+        risk: (option("--risk") ?? "high") as "low" | "medium" | "high",
+        agentId: option("--agent") as never,
+        taskId: option("--task") as never,
+      },
+    );
+    print({ ok: true, approvalId });
+    return;
+  }
+
+  if (command === "tool") {
+    const sessionRuntime = requireSessionRuntime(runtime, "dench tool");
+
+    if (subcommand === "status") {
+      await printToolStatus(sessionRuntime, positional(2));
+      return;
+    }
+
+    if (subcommand === "connect") {
+      const toolkit = positional(2);
+      if (!toolkit) throw new Error("Missing toolkit");
+      const result = await sessionRuntime.client.action(
+        api.functions.agentToolsNode.agentToolConnect,
+        {
+          sessionToken: sessionRuntime.sessionToken,
+          toolkit,
+          callbackUrl: option("--callback-url"),
+        },
+      );
+      print(
+        json ? withToolConnectSummary(result) : formatToolConnectResult(result),
+      );
+      return;
+    }
+
+    if (subcommand === "search") {
+      const query = positional(2);
+      if (!query) throw new Error("Missing search query");
+      try {
+        printToolSearchResult(
+          await sessionRuntime.client.action(
+            api.functions.agentToolsNode.agentToolSearch,
+            {
+              sessionToken: sessionRuntime.sessionToken,
+              query,
+              toolkit: option("--toolkit"),
+              limit: parseNumberOption("--limit"),
+            },
+          ),
+        );
+      } catch (error) {
+        const unavailable = toolGatewayUnavailable(error, {
+          query,
+          toolkit: option("--toolkit"),
+        });
+        if (!unavailable) throw error;
+        print(json ? unavailable : formatToolUnavailable(unavailable));
+      }
+      return;
+    }
+
+    if (subcommand === "run") {
+      const toolSlug = positional(2);
+      if (!toolSlug) throw new Error("Missing Composio tool slug");
+      printToolRunResult(
+        sessionRuntime,
+        await sessionRuntime.client.action(
+          api.functions.agentToolsNode.agentToolRun,
+          {
+            sessionToken: sessionRuntime.sessionToken,
+            toolSlug,
+            arguments: parseJsonObjectOption("--args"),
+            connectedAccountId: option("--account"),
+            approvalId: option("--approval") as never,
+          },
+        ),
+      );
+      return;
+    }
+
+    throw new Error(`Unknown tool command: ${filteredArgs.join(" ")}`);
+  }
+
+  if (
+    command === "approval" &&
+    (subcommand === "approve" || subcommand === "reject")
+  ) {
+    const approvalId = positional(2);
+    if (!approvalId) throw new Error("Missing approval id");
+    const sessionRuntime = requireSessionRuntime(
+      runtime,
+      "dench approval approve/reject",
+    );
+    const decision = subcommand === "approve" ? "approved" : "rejected";
+    const result = await sessionRuntime.client.mutation(
+      api.functions.agentWorkspace.agentDecideApproval,
+      {
+        sessionToken: sessionRuntime.sessionToken,
+        approvalId: approvalId as never,
+        decision,
+        evidence: option("--evidence"),
+      },
+    );
+    throwIfCliError(result);
+    print(result);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${filteredArgs.join(" ")}`);
+}
+
+main().catch((error) => {
+  const extra = error instanceof CliError ? error.payload : {};
+  const payload: JsonRecord = {
+    ok: false,
+    ...extra,
+    error: error instanceof Error ? error.message : String(error),
+  };
+  if (json) {
+    console.error(JSON.stringify(payload, null, 2));
+  } else {
+    console.error(`Error: ${payload.error}`);
+    const nextActions = stringArrayField(payload, "nextActions");
+    if (nextActions.length > 0) {
+      console.error("Next actions:");
+      for (const action of nextActions) {
+        console.error(`  - ${action}`);
+      }
+    }
+  }
+  process.exit(1);
+});