@monster-orange/den 0.4.5 → 0.4.7

package/src/shared/dev-metrics/emit.ts

@@ -19,6 +19,12 @@
  * else). A DSN, in the env or a synced dev-metrics.config, is where to send
  * once opted in; on its own it never sends.
  *
+ * Each line also has `cwd` (den#5): where the command ran, relative to the
+ * distribution root ("." for the root itself), or "outside" for anywhere
+ * else, never an absolute or home path. `<cli> doctor` reads it to spot
+ * polling loops (polling.ts). Like every field, it is sent only when opted
+ * in; the envelope format is unchanged.
+ *
  * Guarantees: never throws, never blocks the caller (the Sentry ship is
  * fire-and-forget, bounded to ~2s). CI=true / DEV_METRICS_DISABLED=1 suppress
  * shipping but still buffer the JSONL locally.
@@ -31,7 +37,7 @@
 
 import * as fs from "fs";
 import * as path from "path";
-import { execFileSync } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import { createHash, randomUUID } from "crypto";
 import * as yaml from "yaml";
 import { getDistRoot } from "../paths.js";
@@ -115,6 +121,29 @@ function commonFields(event: string, root: string): Record<string, string> {
   };
 }
 
+/** The JSONL file, under the repo root. */
+export function eventsFile(root: string = repoRoot()): string {
+  return path.join(root, ".dev-metrics", "events.jsonl");
+}
+
+/**
+ * `cwd` for a local line: the path from the root to cwd ("." for the root,
+ * "/"-separated), or "outside" when cwd is not under the root.
+ */
+export function cwdField(root: string, cwd: string = process.cwd()): string {
+  const real = (p: string): string => {
+    try {
+      return fs.realpathSync(p);
+    } catch {
+      return path.resolve(p);
+    }
+  };
+  const rel = path.relative(real(root), real(cwd));
+  if (rel === "") return ".";
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return "outside";
+  return rel.split(path.sep).join("/");
+}
+
 function isoNoMillis(): string {
   return new Date().toISOString().replace(/\.\d+Z$/, "Z");
 }
@@ -241,6 +270,32 @@ export function buildEnvelope(
   return `{}\n${itemHeader}\n${payload}\n`;
 }
 
+/**
+ * Send from a short-lived detached process instead of this one. The CLI
+ * records its run in the `exit` handler, where an async fetch never runs;
+ * a detached sender outlives the CLI and gives up after SHIP_TIMEOUT_MS.
+ * The long-lived server keeps the in-process fetch.
+ */
+let shipDetached = false;
+export function shipFromDetachedSender(): void {
+  shipDetached = true;
+}
+
+const SENDER = `fetch(process.env.DM_URL,{method:"POST",headers:{"Content-Type":"application/x-sentry-envelope","X-Sentry-Auth":process.env.DM_AUTH},body:process.env.DM_BODY,signal:AbortSignal.timeout(${SHIP_TIMEOUT_MS})}).catch(()=>{}).finally(()=>process.exit(0))`;
+
+function sendDetached(url: string, auth: string, body: string): void {
+  try {
+    spawn(process.execPath, ["-e", SENDER], {
+      detached: true,
+      stdio: "ignore",
+      // Only what the sender needs: none of the caller's environment.
+      env: { DM_URL: url, DM_AUTH: auth, DM_BODY: body },
+    }).unref();
+  } catch {
+    /* fail-open: the JSONL line is already buffered */
+  }
+}
+
 function ship(
   record: Record<string, string>,
   epoch: number,
@@ -266,6 +321,7 @@ function ship(
 
   const url = `${parsed.scheme}://${parsed.host}/api/${parsed.projectId}/envelope/`;
   const auth = `Sentry sentry_key=${parsed.key}, sentry_version=7, sentry_client=dev-metrics-${product().cli}/1.0`;
+  if (shipDetached) return sendDetached(url, auth, envelope);
   // Fire-and-forget: never awaited, so the caller never blocks. Bounded by a 2s
   // abort so a hung ingest can't leak a pending request in the long-lived server.
   void fetch(url, {
@@ -307,14 +363,12 @@ export function record(
     for (const [k, v] of Object.entries(fields)) {
       obj[k] = v == null ? "" : String(v);
     }
+    obj.cwd = cwdField(root);
 
     try {
       const dir = path.join(root, ".dev-metrics");
       fs.mkdirSync(dir, { recursive: true });
-      fs.appendFileSync(
-        path.join(dir, "events.jsonl"),
-        JSON.stringify(obj) + "\n",
-      );
+      fs.appendFileSync(eventsFile(root), JSON.stringify(obj) + "\n");
     } catch {
       /* non-writable dir → fail-open */
     }

package/src/shared/dev-metrics/polling.ts

@@ -0,0 +1,135 @@
+/**
+ * Polling-loop warning (den#5) for `<cli> doctor`: one command, run from
+ * one place, more than POLL_LIMIT times in any POLL_WINDOW_MS window looks
+ * like an agent polling it. Local only: it reads the tail of the local
+ * .dev-metrics/events.jsonl and sends nothing anywhere.
+ *
+ * A line's place is its `cwd` (emit.ts). An older line has none, so it is
+ * keyed by its `repo` instead.
+ */
+import * as fs from "fs";
+
+/** More calls than this in one window is a polling loop. */
+export const POLL_LIMIT = 600;
+/** The window: an hour. */
+export const POLL_WINDOW_MS = 60 * 60 * 1000;
+/** At most this much of the file's end is read, however big it is. */
+export const TAIL_BYTES = 8 * 1024 * 1024;
+
+/**
+ * The file's last `max` bytes as whole lines: a line cut by the start of
+ * the slice is dropped. A missing or unreadable file is no lines.
+ */
+export function readTailLines(
+  file: string,
+  max: number = TAIL_BYTES,
+): string[] {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(file, "r");
+    const size = fs.fstatSync(fd).size;
+    const len = Math.min(size, max);
+    const buf = Buffer.alloc(len);
+    let got = 0;
+    while (got < len) {
+      const n = fs.readSync(fd, buf, got, len - got, size - len + got);
+      if (n <= 0) break;
+      got += n;
+    }
+    const lines = buf.subarray(0, got).toString("utf-8").split("\n");
+    if (len < size) lines.shift();
+    return lines.filter((l) => l.trim());
+  } catch {
+    return [];
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+export interface PollingLoop {
+  command: string;
+  /** Where: the line's cwd, or `repo <name>` for an older line. */
+  where: string;
+  /** Calls in the busiest window. */
+  calls: number;
+  /** The busiest window's first and last call (ISO, no millis). */
+  from: string;
+  to: string;
+}
+
+const iso = (ms: number): string =>
+  new Date(ms).toISOString().replace(/\.\d+Z$/, "Z");
+
+/**
+ * Every command+place with more than `limit` calls in some `windowMs`
+ * window, with its busiest window. Lines that aren't JSON, or have no
+ * command or time, are skipped.
+ */
+export function findPollingLoops(
+  lines: string[],
+  limit: number = POLL_LIMIT,
+  windowMs: number = POLL_WINDOW_MS,
+): PollingLoop[] {
+  const byKey = new Map<
+    string,
+    { command: string; where: string; times: number[] }
+  >();
+  for (const line of lines) {
+    let o: Record<string, unknown>;
+    try {
+      o = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    if (!o || typeof o !== "object") continue;
+    const command = typeof o.command === "string" ? o.command : "";
+    const t = typeof o.ts === "string" ? Date.parse(o.ts) : NaN;
+    if (!command || Number.isNaN(t)) continue;
+    const where =
+      typeof o.cwd === "string" && o.cwd
+        ? o.cwd
+        : `repo ${typeof o.repo === "string" && o.repo ? o.repo : "?"}`;
+    const key = `${command}\u0000${where}`;
+    let e = byKey.get(key);
+    if (!e) byKey.set(key, (e = { command, where, times: [] }));
+    e.times.push(t);
+  }
+  const out: PollingLoop[] = [];
+  for (const { command, where, times } of byKey.values()) {
+    if (times.length <= limit) continue;
+    times.sort((a, b) => a - b);
+    let best = 0;
+    let bi = 0;
+    let bj = 0;
+    for (let i = 0, j = 0; j < times.length; j++) {
+      while (times[j] - times[i] >= windowMs) i++;
+      if (j - i + 1 > best) {
+        best = j - i + 1;
+        bi = i;
+        bj = j;
+      }
+    }
+    if (best > limit)
+      out.push({
+        command,
+        where,
+        calls: best,
+        from: iso(times[bi]),
+        to: iso(times[bj]),
+      });
+  }
+  return out.sort((a, b) => b.calls - a.calls);
+}
+
+/** One warning line, as doctor prints it. */
+export function pollingWarning(p: PollingLoop): string {
+  return `looks like a polling loop: ${p.command} in ${p.where}, ${p.calls} calls in an hour (${p.from}–${p.to})`;
+}
+
+/** doctor's warnings for this events file (none when it is fine or absent). */
+export function pollingWarnings(
+  file: string,
+  max: number = TAIL_BYTES,
+): string[] {
+  return findPollingLoops(readTailLines(file, max)).map(pollingWarning);
+}

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/shared/port-pick.ts

@@ -0,0 +1,60 @@
+/**
+ * Picking a free localhost port for a new distribution's web server
+ * (`create`, ON-2), so a second Den on one machine doesn't collide with the
+ * first on DEFAULT_PORT.
+ *
+ * "In use" is checked without talking to whoever holds the port: a TCP
+ * connect that is closed as soon as it opens (no byte is sent), then a
+ * bind. Either one finding something there means in use.
+ */
+import * as net from "net";
+import { RESERVED_DEN_PORTS } from "./constants.js";
+
+/** Whether something holds `port` on localhost. Never sends a byte. */
+export function portInUse(port: number, host = "localhost"): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = net.connect({ host, port });
+    const done = (inUse: boolean | null) => {
+      sock.destroy();
+      if (inUse !== null) return resolve(inUse);
+      // Nothing accepted a connection: can we bind it ourselves?
+      const srv = net.createServer();
+      srv.once("error", () => resolve(true));
+      srv.listen({ port, host, exclusive: true }, () =>
+        srv.close(() => resolve(false)),
+      );
+    };
+    sock.setTimeout(1_000);
+    sock.once("connect", () => done(true));
+    // Something there that doesn't complete a handshake: in use.
+    sock.once("timeout", () => done(true));
+    sock.once("error", (e: NodeJS.ErrnoException) =>
+      done(e.code === "ECONNREFUSED" ? null : true),
+    );
+  });
+}
+
+export interface PickPortOptions {
+  /** The port wanted (the default); the search goes up from here. */
+  start: number;
+  /** Never chosen. */
+  reserved?: readonly number[];
+  /** How many ports above `start` to try. */
+  span?: number;
+  inUse?: (port: number) => Promise<boolean>;
+}
+
+/**
+ * `start` when it is free, else the first free port above it that is not
+ * reserved; null when none in the span is free.
+ */
+export async function pickFreePort(o: PickPortOptions): Promise<number | null> {
+  const reserved = o.reserved ?? RESERVED_DEN_PORTS;
+  const inUse = o.inUse ?? ((p: number) => portInUse(p));
+  const span = o.span ?? 100;
+  for (let p = o.start; p <= Math.min(o.start + span, 65535); p++) {
+    if (reserved.includes(p)) continue;
+    if (!(await inUse(p))) return p;
+  }
+  return null;
+}

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/create-main.ts

@@ -6,4 +6,4 @@
 import { runCreate } from "./create.js";
 
 const cwd = process.env.DEN_INVOKE_CWD?.trim() || process.cwd();
-process.exit(runCreate(process.argv.slice(2), cwd));
+process.exit(await runCreate(process.argv.slice(2), cwd));