@monster-orange/den 0.4.6 → 0.4.8

package/src/ui/cli/agents-command.ts

@@ -20,10 +20,17 @@
  *           persona, runtime and model; a record whose session is gone is
  *           listed as stopped or ended. A plain session is not an agent.
  *   stop    ends its session (TERM) and marks the record stopped.
- *   resume  only when its runtime declares resume and its session is not
- *           running: a new session, in the same cwd, continuing the last run;
+ *   resume  only when its runtime declares resume, its record holds the
+ *           runtime's resume token, and its session is not running: a new
+ *           session, in the same cwd and workspace with the grants it had,
+ *           continuing the last conversation (den-claude: --resume <token>);
  *           when that session was never prompted, a fresh start under the
  *           same conversation id (there is nothing to continue).
+ *           --all-interrupted (AG-14.3): every agent interrupted when Den or
+ *           the machine restarted that can resume.
+ *   rm      (AG-14.1b) forgets a stopped, interrupted or exited agent (never
+ *           a running one); --stopped forgets every one of -w <ws> (or of
+ *           every workspace). The runtime's own history stays.
  *   doctor  (AG-0.3, AG-0.5) each runtime of the catalog, installed
  *           first: its status, the CLI it runs and where that came from
  *           (workspace or user.yml setting, login shell, PATH, install
@@ -33,21 +40,30 @@
  *           fix when it is missing. Exit 1 when the default runtime is
  *           unavailable. It resolves the login shell's PATH first, as the
  *           web server does at start.
+ *   handback-check <file|->  (den#5) the hand-back check (handback.ts) on a
+ *           file or stdin: each problem on its own line, exit 1 when there
+ *           is one, 0 when the hand-back is complete and plain.
  *
  * Nothing here takes a grant: grants come from the org config only. The
  * host enforces agents.max_concurrent on every start, counting agents only.
  */
+import * as fs from "fs";
 import { DEFAULT_RUNTIME_ID } from "../../shared/agents/runtimes.js";
 import { initLoginPath } from "../../shared/agents/runtime-search.js";
 import { HostError } from "../../shared/sessions/client.js";
+import { checkHandback } from "../../shared/agents/handback.js";
+import { listRecords } from "../../shared/agents/records.js";
 import {
   AgentError,
   listAgents,
   listPersonas as personaList,
   listRuntimes,
   loadAgentWorkspaces,
+  removeAgent,
+  removeStopped,
   resolveAgentsDeps,
   resumeAgent,
+  resumeInterrupted,
   startAgent,
   stopAgent,
   type AgentsDeps,
@@ -75,25 +91,41 @@ export {
 } from "./agent-ops.js";
 
 export const AGENTS_HELP = {
-  usage: "agents <list|start|stop|resume|personas|doctor> ...",
+  usage:
+    "agents <list|start|stop|resume|rm|personas|doctor|handback-check> ...",
   lines: [
     "Agents: a persona and a workspace, run by a runtime in a session that",
     "outlives the web server (see `{cli} sessions`).",
     "",
-    "{cli} agents list -w <ws> [--json]",
+    "{cli} agents list -w <ws> [--stopped] [--json]",
+    "    --stopped: only the stopped, interrupted and exited ones",
     "{cli} agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>] [--id <id>]",
     "    runs in the workspace's dir as <dist>-<ws>:<id>; its MCP is pinned to <ws>",
     "    (plus agents.<id>.grants); capped by agents.max_concurrent",
-    "{cli} agents stop <id> [-w <ws>]",
+    "{cli} agents stop <id> [-w <ws>] [--no-wait]",
+    "    waits up to 5 s for the session to end (else: still stopping, exit 1);",
+    "    --no-wait: return once TERM is sent",
     "{cli} agents resume <id> [-w <ws>]",
-    "    only when its runtime declares resume and its session has ended;",
-    "    a session never prompted starts fresh under the same conversation id",
+    "{cli} agents resume --all-interrupted [-w <ws>]",
+    "    the same conversation, persona, workspace and folder, when its runtime",
+    "    can resume one and its session has ended; with nothing to resume yet,",
+    "    it starts fresh under the same conversation id. --all-interrupted: every",
+    "    agent interrupted when Den or the machine restarted",
+    "{cli} agents rm <id> [-w <ws>]",
+    "{cli} agents rm --stopped [-w <ws>]",
+    "    forget a stopped, interrupted or exited agent (never a running one);",
+    "    the runtime keeps its own history. agents.remove_stopped_after in",
+    "    user.yml (never, 1d, 7d) forgets stopped ones on its own",
     "{cli} agents personas [--json]",
     "    Den's default pack, then agents.persona_packs (a later pack wins by id)",
     "{cli} agents doctor [-w <ws>] [--json]",
     "    each runtime, installed first: status, the CLI it runs and where it came",
     "    from, its version, the directories searched, and the fix; exit 1 when the",
     "    default is missing. -w: as that workspace's agents find them",
+    "{cli} agents handback-check <file|-> [--json]",
+    "    checks a hand-back to a person: URL, machine, branch, what changed, what",
+    "    to click and decisions are all there, every ID is explained, and each",
+    "    decision is a numbered yes/no question; exit 1 with what to fix",
     "",
     "Runtimes: den-claude (default; Claude Code's claude), codex (OpenAI's Codex",
     "CLI), gemini (Google's Gemini CLI), grok (xAI's Grok Build), and generic (the",
@@ -111,17 +143,27 @@ export const AGENTS_HELP = {
 
 async function list(args: string[], d: AgentsResolved): Promise<number> {
   const where = "agents list";
-  const p = parseArgs(where, args, { "--workspace": true, "--json": false });
+  const p = parseArgs(where, args, {
+    "--workspace": true,
+    "--json": false,
+    "--stopped": false,
+  });
   noExtra(where, p);
   const ws = workspaceFlag(where, p);
   if (!ws) throw new UsageError(`${where} needs -w <workspace>`);
-  const rows = await listAgents(d, ws);
+  const rows = await listAgents(d, ws, {
+    stopped: p.flags["--stopped"] === true,
+  });
   if (p.flags["--json"]) {
     d.out(JSON.stringify(rows, null, 2));
     return 0;
   }
   if (!rows.length) {
-    d.out(`no agents in ${ws}`);
+    d.out(
+      p.flags["--stopped"]
+        ? `no stopped agents in ${ws}`
+        : `no agents in ${ws}`,
+    );
     return 0;
   }
   for (const l of columns([
@@ -223,22 +265,40 @@ function idAndWorkspace(
 }
 
 async function stop(args: string[], d: AgentsResolved): Promise<number> {
-  const { id, ws } = idAndWorkspace("agents stop", args);
-  const { rec, session: s } = await stopAgent(d, id, ws);
+  // --no-wait: return once TERM is sent (before 0.4.8, always).
+  const wait = !args.includes("--no-wait");
+  const { id, ws } = idAndWorkspace(
+    "agents stop",
+    args.filter((a) => a !== "--no-wait"),
+  );
+  const {
+    rec,
+    session: s,
+    stillStopping,
+  } = await stopAgent(d, id, ws, {
+    wait,
+  });
+  if (stillStopping) {
+    d.err(
+      `${rec.id} is still stopping (sent TERM to ${s!.name}, pid ${s!.pid}; not ended after ${d.stopWaitMs / 1000} s)`,
+    );
+    return 1;
+  }
   d.out(
     s
-      ? `stopped agent ${rec.id} (sent TERM to ${s.name}, pid ${s.pid})`
+      ? `stopped agent ${rec.id} (sent TERM to ${s.name}, pid ${s.pid}${wait && d.stopWaitMs > 0 ? "; it has ended" : ""})`
       : `agent ${rec.id} was not running; marked stopped`,
   );
   return 0;
 }
 
 async function resume(args: string[], d: AgentsResolved): Promise<number> {
+  if (args.includes("--all-interrupted")) return resumeAll(args, d);
   const { id, ws } = idAndWorkspace("agents resume", args);
   const s = await resumeAgent(d, id, ws);
   if (s.fresh)
     d.out(
-      `agent ${s.rec.id}: starting fresh: it was never prompted, so there is no conversation to resume`,
+      `agent ${s.rec.id}: nothing to resume yet; started fresh (same conversation id, folder and scope)`,
     );
   return report(
     d,
@@ -247,6 +307,58 @@ async function resume(args: string[], d: AgentsResolved): Promise<number> {
   );
 }
 
+/** `agents resume --all-interrupted [-w <ws>]` (AG-14.3). */
+async function resumeAll(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents resume";
+  const p = parseArgs(where, args, {
+    "--workspace": true,
+    "--all-interrupted": false,
+  });
+  noExtra(where, p);
+  const ws = workspaceFlag(where, p);
+  const r = await resumeInterrupted(d, ws ? [ws] : undefined);
+  if (!r.resumed.length && !r.failed.length) {
+    d.out(`no interrupted agents${ws ? ` in ${ws}` : ""}`);
+    return 0;
+  }
+  for (const x of r.resumed)
+    d.out(
+      `${x.fresh ? "started" : "resumed"} agent ${x.rec.id} as ${x.rec.sessionName} in ${x.rec.cwd}`,
+    );
+  for (const f of r.failed) d.err(`✗ agent ${f.agent}: ${f.why}`);
+  return r.failed.length ? 1 : 0;
+}
+
+/** `agents rm <id> [-w <ws>]`, `agents rm --stopped [-w <ws>]` (AG-14.1b). */
+async function rm(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents rm";
+  const p = parseArgs(where, args, { "--workspace": true, "--stopped": false });
+  noExtra(where, p, 1);
+  const ws = workspaceFlag(where, p);
+  const id = p.positional[0];
+  if (p.flags["--stopped"]) {
+    if (id) throw new UsageError(`${where}: give <id> or --stopped, not both`);
+    if (ws && !d.workspaceExists(ws))
+      throw new UsageError(`${where}: workspace "${ws}" does not exist`);
+    const wss = ws
+      ? [ws]
+      : [...new Set(listRecords(d.stateDir()).map((r) => r.workspace))];
+    const gone = await removeStopped(d, wss);
+    d.out(
+      gone.length
+        ? `removed ${gone.length} stopped ${gone.length === 1 ? "agent" : "agents"}: ${gone.map((g) => g.agent).join(", ")}`
+        : `no stopped agents${ws ? ` in ${ws}` : ""}`,
+    );
+    return 0;
+  }
+  if (!id) throw new UsageError(`${where} needs <id> or --stopped`);
+  const [gone] = await removeAgent(d, id, ws);
+  d.out(
+    `removed agent ${gone?.agent ?? id}; its conversation stays in the runtime's own history`,
+  );
+  return 0;
+}
+
 async function listPersonas(
   args: string[],
   d: AgentsResolved,
@@ -276,6 +388,45 @@ async function listPersonas(
 export interface AgentsDoctorDeps {
   /** Resolve the login shell's PATH first (default: initLoginPath). */
   loginPath?: () => Promise<void>;
+  /** Read a hand-back: a file path, or "-" for stdin (handback-check). */
+  readHandback?: (src: string) => Promise<string>;
+}
+
+async function readFileOrStdin(src: string): Promise<string> {
+  if (src !== "-") return fs.promises.readFile(src, "utf-8");
+  let text = "";
+  for await (const chunk of process.stdin) text += String(chunk);
+  return text;
+}
+
+/** `agents handback-check <file|-> [--json]`. */
+async function handbackCheck(
+  args: string[],
+  d: AgentsResolved,
+  deps: AgentsDoctorDeps,
+): Promise<number> {
+  const where = "agents handback-check";
+  const p = parseArgs(where, args, { "--json": false });
+  if (p.positional.length !== 1 || p.rest)
+    throw new UsageError(`${where} takes one file, or - for stdin`);
+  const src = p.positional[0];
+  let text: string;
+  try {
+    text = await (deps.readHandback ?? readFileOrStdin)(src);
+  } catch (e) {
+    d.err(
+      `✗ ${where}: can't read ${src} (${(e as NodeJS.ErrnoException).code ?? "error"})`,
+    );
+    return 1;
+  }
+  const r = checkHandback(text);
+  if (p.flags["--json"]) d.out(JSON.stringify(r, null, 2));
+  else if (r.ok) d.out("✓ the hand-back is complete and plain");
+  else {
+    d.out("✗ the hand-back is not ready:");
+    for (const l of r.problems) d.out(`  - ${l}`);
+  }
+  return r.ok ? 0 : 1;
 }
 
 const SOURCE_WORD: Record<string, string> = {
@@ -393,12 +544,17 @@ export async function cmdAgents(
         case "resume":
           await loadAgentWorkspaces(deps);
           return await resume(rest, d);
+        case "rm":
+          await loadAgentWorkspaces(deps);
+          return await rm(rest, d);
         case "personas":
           return await listPersonas(rest, d);
         case "doctor":
           // -w checks the workspace exists, and reads its runtime paths.
           await loadAgentWorkspaces(deps);
           return await doctor(rest, d, deps);
+        case "handback-check":
+          return await handbackCheck(rest, d, deps);
         default:
           throw new UsageError(`unknown agents command "${sub}"`);
       }

package/src/ui/cli/doctor-command.ts

@@ -15,12 +15,19 @@
  * plain session and each available runtime's agent env (env-probe.ts), and
  * exits 1 when a runtime's scrubEnv name or a credential-shaped variable
  * reaches one. Without the PTY module the probe is unavailable, not failed.
+ *
+ * It also reads the tail of the local .dev-metrics/events.jsonl (bounded,
+ * polling.ts) and warns when one command, run from one place, ran more than
+ * 600 times in an hour: an agent polling it. A warning, never a failure;
+ * nothing is sent.
  */
 import chalk from "chalk";
 import { readDenConfig, type DenConfig } from "../../shared/den-config.js";
 import { getStateDir } from "../../shared/paths.js";
 import { product } from "../../shared/product.js";
 import { listRecords } from "../../shared/agents/records.js";
+import { eventsFile } from "../../shared/dev-metrics/emit.js";
+import { pollingWarnings } from "../../shared/dev-metrics/polling.js";
 import { readBrand } from "../../shared/brand.js";
 import { hasEdgeBlock, readEdgeConfig } from "../../shared/edge/config.js";
 import { edgeTlsWarnings, tlsStrategyFor } from "../../shared/edge/tls.js";
@@ -219,6 +226,18 @@ export function doctorNotes(cli: string, configured: boolean): string[] {
     : [];
 }
 
+/** The polling-loop warnings for this events file, as doctor prints them. */
+export function pollingLines(file: string, title: string): string[] {
+  const warnings = pollingWarnings(file);
+  if (!warnings.length) return [];
+  return [
+    "",
+    chalk.bold(`${title} doctor: dev-metrics (local, never sent)`),
+    "",
+    ...warnings.map((w) => chalk.yellow(`  ⚠ ${w}`)),
+  ];
+}
+
 function readConfigOrNull(): DenConfig | null {
   try {
     return readDenConfig();
@@ -293,6 +312,7 @@ export async function cmdDoctor(args: string[]): Promise<number> {
   }
   const rows = doctorRows();
   for (const l of formatDoctor(rows, readBrand().name)) console.log(l);
+  for (const l of pollingLines(eventsFile(), readBrand().name)) console.log(l);
   const cli = product().cli;
   if (!probe) {
     for (const l of doctorNotes(

package/src/ui/cli/flag-parser.ts

@@ -215,6 +215,7 @@ const COMMAND_FLAGS: Record<string, readonly string[]> = {
     "--json",
   ],
   down: [
+    "--json",
     "--manifest",
     "--no-derive",
     "-a",

package/src/ui/cli/index.ts

@@ -196,6 +196,7 @@ import { cmdEdge } from "./edge-command.js";
 import { cmdDoctor } from "./doctor-command.js";
 import { cmdSessions, SESSIONS_HELP } from "./sessions-command.js";
 import { AGENTS_HELP, cmdAgents } from "./agents-command.js";
+import { USAGE_HELP, cmdUsage } from "./usage-command.js";
 import { cmdService } from "./service-command.js";
 import { cmdStack } from "./stack-command.js";
 import { cmdTheme } from "./theme-command.js";
@@ -536,6 +537,7 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   },
   sessions: SESSIONS_HELP,
   agents: AGENTS_HELP,
+  usage: USAGE_HELP,
 };
 
 function resolveCliBaseApiUrl(explicitBaseApiUrl?: string): string | undefined {
@@ -588,6 +590,7 @@ const TELEMETRY_COMMANDS = new Set<string>([
   "mcp",
   "sessions",
   "agents",
+  "usage",
   "service",
   "theme",
   "plugin",
@@ -616,6 +619,8 @@ const CONFIG_FREE_COMMANDS = new Set<string>([
   // listing a session is never stranded by a config that fails (AG-3a).
   "sessions",
   "agents",
+  // den#6: reads local transcripts and agent records, no org data.
+  "usage",
 ]);
 
 function configCheckedCommand(command: string): boolean {
@@ -900,6 +905,12 @@ class DenCLI {
 
         case "web": {
           const sub = args[1];
+          if (args.includes("--json") && (sub === "down" || sub === "stop")) {
+            process.exitCode = await this.cmdWebDownJson(
+              args.slice(1).filter((a) => a !== "--json"),
+            );
+            break;
+          }
           if (
             args.includes("--json") &&
             (sub === undefined ||
@@ -926,7 +937,11 @@ class DenCLI {
           break;
 
         case "down":
-          await this.cmdServiceDown(args.slice(1));
+          if (args.slice(1).includes("--json"))
+            process.exitCode = await this.cmdServiceDownJson(
+              args.slice(1).filter((a) => a !== "--json"),
+            );
+          else await this.cmdServiceDown(args.slice(1));
           break;
 
         case "restart":
@@ -1072,6 +1087,10 @@ class DenCLI {
           process.exitCode = await cmdAgents(args.slice(1));
           break;
 
+        case "usage":
+          process.exitCode = await cmdUsage(args.slice(1));
+          break;
+
         case "mcp": {
           // Setup subcommands: register the server with agents.
           const { MCP_CONNECT_SUBCOMMANDS, runMcpConnect } =
@@ -3276,6 +3295,101 @@ class DenCLI {
     return out.ok ? 0 : 1;
   }
 
+  /**
+   * `down --json`: down as it always runs, its log on stderr, then one JSON
+   * object on stdout, `{ ok, workspace, services, all? }`. Safe to re-run:
+   * stopping what is already stopped is ok. A failure names a fix.
+   */
+  private async cmdServiceDownJson(args: string[]): Promise<number> {
+    const bin = fs.existsSync(
+      nodePath.join(getDistRoot(), "bin", product().cli),
+    )
+      ? `./bin/${product().cli}`
+      : product().cli;
+    const before = process.exitCode;
+    process.exitCode = undefined;
+    let error: string | undefined;
+    try {
+      await quietStdout(() => this.cmdServiceDown(args));
+    } catch (e) {
+      if (!(e instanceof ExitRequested)) error = (e as Error).message;
+      else if (e.code !== 0) process.exitCode = e.code;
+    }
+    const failedExit = process.exitCode !== undefined && process.exitCode !== 0;
+    process.exitCode = before;
+    const terminator = args.indexOf("--");
+    const own = terminator === -1 ? args : args.slice(0, terminator);
+    const all = own.includes("-a") || own.includes("--all");
+    const out: Record<string, unknown> = {
+      ok: !error && !failedExit,
+      workspace:
+        process.env.DEN_WORKSPACE_OVERRIDE ?? getFocusedWorkspaceName() ?? null,
+      services: own.filter((a) => !a.startsWith("-")),
+      ...(all ? { all: true } : {}),
+    };
+    if (!out.ok) {
+      out.error = error ?? "down failed (its log is on stderr)";
+      out.fix = `${bin} doctor --json`;
+    }
+    printJson(out);
+    return out.ok ? 0 : 1;
+  }
+
+  /**
+   * `web down --json`: the web server stopped as usual (its log on stderr),
+   * then `{ ok, url, port, running: false, stopped }` once nothing answers
+   * (up to 10s). `stopped` is false when it wasn't running: re-running is ok.
+   */
+  private async cmdWebDownJson(args: string[]): Promise<number> {
+    const { parseWebCommandArgs } = await import("./web-command.js");
+    const { probeWebServer } = await import("./mcp-connect.js");
+    const bin = fs.existsSync(
+      nodePath.join(getDistRoot(), "bin", product().cli),
+    )
+      ? `./bin/${product().cli}`
+      : product().cli;
+    let port: number;
+    try {
+      port = parseWebCommandArgs(args).port;
+    } catch (e) {
+      printJson({
+        ok: false,
+        error: (e as Error).message,
+        fix: `${bin} web down --json`,
+      });
+      return 2;
+    }
+    const url = `http://localhost:${port}`;
+    const was = (await probeWebServer(url)).kind === "up";
+    let error: string | undefined;
+    try {
+      await quietStdout(() => cmdWeb(args));
+    } catch (e) {
+      if (!(e instanceof ExitRequested) || e.code !== 0)
+        error = (e as Error).message;
+    }
+    let probe = await probeWebServer(url);
+    const deadline = Date.now() + 10_000;
+    while (!error && probe.kind === "up" && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 250));
+      probe = await probeWebServer(url);
+    }
+    const running = probe.kind === "up";
+    const out: Record<string, unknown> = {
+      ok: !error && !running,
+      url,
+      port,
+      running,
+      stopped: was && !running,
+    };
+    if (!out.ok) {
+      out.error = error ?? `the web server still answers at ${url}`;
+      out.fix = `${bin} doctor --json`;
+    }
+    printJson(out);
+    return out.ok ? 0 : 1;
+  }
+
   /**
    * `web up|restart --json` (ON-2): the web server started as usual (its
    * log on stderr), then `{ ok, url, port, version? }` once it answers
@@ -5193,7 +5307,10 @@ class DenCLI {
     );
     console.log("  agents list -w <ws>  The workspace's agents");
     console.log(
-      "  agents start -w <ws> --persona <p>  Run a persona in the workspace (stop, resume, personas)",
+      "  agents start -w <ws> --persona <p>  Run a persona in the workspace (stop, resume, rm, personas)",
+    );
+    console.log(
+      "  usage agents|report      Agents' tokens and outcomes, from local transcripts (never sent)",
     );
     console.log();
     console.log(