@monster-orange/den 0.4.6 → 0.4.7

package/src/shared/engine.ts

@@ -93,11 +93,23 @@ export function playwrightCommand(...args: string[]): EngineCommand {
  * or with DEN_USE_DIST=1. Mirrors the web server's resolveServerEntrypoint.
  */
 export function cliEntrypoint(engine: string = getEngineRoot()): EngineCommand {
-  const built = path.join(engine, "dist/src/ui/cli/index.js");
+  return scriptEntrypoint("src/ui/cli/index.ts", engine);
+}
+
+/**
+ * How to run one of Den's TypeScript entry points (`src/….ts`, relative to
+ * the engine root) as a node process: cliEntrypoint's rules, for any
+ * script (an agent's hook, guardrails/stop-hook.ts).
+ */
+export function scriptEntrypoint(
+  rel: string,
+  engine: string = getEngineRoot(),
+): EngineCommand {
+  const built = path.join(engine, "dist", rel.replace(/\.ts$/, ".js"));
   if (process.env.DEN_USE_DIST === "1" && fs.existsSync(built))
     return { command: process.execPath, args: [built] };
   const loader = engineModuleFile("tsx/dist/loader.mjs", engine);
-  const src = path.join(engine, "src/ui/cli/index.ts");
+  const src = path.join(engine, rel);
   if (loader && fs.existsSync(src))
     return {
       command: process.execPath,

package/src/ui/cli/agent-ops.ts

@@ -437,20 +437,24 @@ function personas(
   cfg: ResolvedAgentsConfig,
 ): Map<string, Persona> {
   try {
-    return loadPersonas(resolvePackDirs(cfg.personaPacks, d.distRoot()));
+    return loadPersonas(
+      resolvePackDirs(cfg.personaPacks, d.distRoot()),
+      undefined,
+      { defaultPack: cfg.defaultPackGuardrails, packs: cfg.packGuardrails },
+    );
   } catch (e) {
     throw refused((e as Error).message, [], 422);
   }
 }
 
 /** A persona as listed: everything but its role prompt. */
-export type ListedPersona = Omit<Persona, "prompt">;
+export type ListedPersona = Omit<Persona, "prompt" | "guardrailsSet">;
 
 /** Den's default pack, then agents.persona_packs, by id. */
 export function listPersonas(d: AgentsResolved): ListedPersona[] {
   return [...personas(d, agentsConfig(d)).values()]
     .sort((a, b) => a.id.localeCompare(b.id))
-    .map(({ prompt: _p, ...rest }) => rest);
+    .map(({ prompt: _p, guardrailsSet: _g, ...rest }) => rest);
 }
 
 export interface RuntimeChoice {

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

@@ -33,13 +33,18 @@
  *           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 {
   AgentError,
   listAgents,
@@ -75,7 +80,7 @@ export {
 } from "./agent-ops.js";
 
 export const AGENTS_HELP = {
-  usage: "agents <list|start|stop|resume|personas|doctor> ...",
+  usage: "agents <list|start|stop|resume|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`).",
@@ -94,6 +99,10 @@ export const AGENTS_HELP = {
     "    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",
@@ -276,6 +285,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> = {
@@ -399,6 +447,8 @@ export async function cmdAgents(
           // -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

@@ -900,6 +900,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 +932,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":
@@ -3276,6 +3286,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

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

@@ -1196,7 +1196,9 @@ export function displayWebHelp(): void {
   console.log("  --port, -p <port>  Use a non-default web port");
   console.log(
     "  --no-open          Start or check the server without opening a browser",
-    "  --json             (up, restart) log on stderr; stdout: { ok, url, port, version? }",
+  );
+  console.log(
+    "  --json             log on stderr; stdout: up, restart { ok, url, port, version? }; down { ok, url, port, running, stopped }",
   );
   console.log(
     "  --setup-browser-access  Request macOS Automation access for browser tab reuse",