@monster-orange/den 0.4.7 → 0.4.9

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

@@ -28,11 +28,24 @@
  *           listed as stopped or ended. A plain session is not an agent.
  *   stop    ends its session (TERM), marks the record stopped and revokes
  *           its actor token.
- *   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, the record has its
+ *           resume token, and its session is not running: a new session,
+ *           in the same cwd and workspace with the grants it had (never
+ *           more than the config still gives), continuing the last run with
+ *           the runtime's own resume (den-claude: `--resume <token>`);
  *           when that session was never prompted, a fresh start under the
  *           same conversation id (there is nothing to continue). A fresh
  *           actor token; the old one stops working.
+ *   fresh   (AG-14) a new conversation with the same persona, runtime,
+ *           model and workspace, under the same id.
+ *   remove  (AG-14.1b) forgets a stopped, interrupted or exited agent: its
+ *           record moves aside for Undo (restore). Never a running one.
+ *           The runtime's own history stays.
+ *   interrupted (AG-14.3) an agent whose session is gone though nobody
+ *           stopped it and it never exited: Den or the machine went down.
+ *           markInterrupted stamps them when the web server starts, and
+ *           resumes the standing personas and those with
+ *           `resume_on_restart: true`.
  *
  * Nothing here takes a grant: grants come from the org config only. The
  * host enforces agents.max_concurrent on every start, counting agents only.
@@ -71,7 +84,10 @@ import {
   AGENT_ID_RE,
   agentFilesDir,
   listRecords,
+  purgeRemoved,
   readRecord,
+  removeRecord,
+  restoreRecord,
   writeRecord,
   writeRuntimeFiles,
   type AgentRecord,
@@ -88,6 +104,20 @@ import {
   type Runtime,
 } from "../../shared/agents/runtimes.js";
 import type { RuntimeDetect } from "../../shared/agents/runtime.js";
+import {
+  archiveHandoff,
+  DEFAULT_ROTATE,
+  handoffFile,
+  handoffPrompt,
+  launchRotation,
+  readHandoff,
+  readRotation,
+  writeRotation,
+  reasonText,
+  rotateAfter,
+  rotationInfo,
+  type RotationInfo,
+} from "../../shared/agents/rotation.js";
 import {
   binSettingKey,
   ensureInteractivePath,
@@ -130,6 +160,11 @@ export interface AgentsDeps extends SessionsDeps {
    * exit (default 3000 ms; 0: not at all).
    */
   exitWatchMs?: number;
+  /**
+   * How long stop waits for the session to end after TERM (default
+   * 5000 ms; 0: it doesn't wait, as `--no-wait`).
+   */
+  stopWaitMs?: number;
   /** `agents.runtimes.<id>.bin` (default: user.yml's; undefined: unset). */
   runtimeBin?: (id: string) => unknown;
   /**
@@ -156,6 +191,7 @@ export interface AgentsResolved extends Resolved {
   workspaceDir: (ws: string) => string;
   mcpServer: () => { command: string[] | string; env: Record<string, string> };
   exitWatchMs: number;
+  stopWaitMs: number;
   runtimeBin: (id: string) => unknown;
   workspaceRuntimeBin: (ws: string, id: string) => unknown;
   userCatalog: (taken: readonly string[]) => CatalogEntry[];
@@ -166,6 +202,8 @@ export interface AgentsResolved extends Resolved {
 /** The early-exit watch: at most this long, polling the host. */
 export const EXIT_WATCH_MS = 3000;
 const EXIT_POLL_MS = 100;
+/** Stop waits at most this long for the session to end (0.4.8). */
+export const STOP_WAIT_MS = 5000;
 /** The most lines of an early exit's scrollback returned. */
 const EXIT_TAIL_LINES = 10;
 
@@ -249,6 +287,7 @@ export function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
       }),
     mcpServer: d.mcpServer ?? (() => defaultMcpServer(base.cli)),
     exitWatchMs: d.exitWatchMs ?? EXIT_WATCH_MS,
+    stopWaitMs: d.stopWaitMs ?? STOP_WAIT_MS,
     runtimeBin: d.runtimeBin ?? ((id) => configuredRuntimeBin(id)),
     workspaceRuntimeBin:
       d.workspaceRuntimeBin ?? ((ws, id) => workspaceRuntimeBin(ws, id)),
@@ -322,49 +361,119 @@ export interface AgentRow {
   workspace?: string;
   cwd?: string;
   /** running, stopping (stopped, its session not yet gone), exited
-   * (<code>), stopped or ended. */
+   * (<code>), stopped or interrupted. */
   state: string;
   /** When its current (or last) session started (ISO 8601). */
   startedAt?: string;
-  /** Resume applies: its runtime declares resume and it isn't running. */
+  /**
+   * Resume applies: its runtime declares resume, its record has the
+   * runtime's resume token, and it isn't running.
+   */
   resumable: boolean;
+  /**
+   * Why Resume doesn't apply to a stopped agent (AG-14.2), e.g. "codex
+   * can't resume a conversation": only Start fresh is offered.
+   */
+  noResume?: string;
+  /** When `agents stop` stopped it. */
+  stoppedAt?: string;
+  /** When its session was seen to end on its own. */
+  endedAt?: string;
+  /** When Den found it interrupted by a restart. */
+  interruptedAt?: string;
+  /** Its persona resumes on its own after a restart (AG-14.3). */
+  autoResume?: boolean;
+  outcome?: AgentRecord["outcome"];
+  usage?: AgentRecord["usage"];
+  /**
+   * Session rotation (den#4): its compactions, whether a rotation is due
+   * and why, and its handoff.md. `ready`: Relaunch from handoff, not Resume.
+   */
+  rotation?: RotationInfo;
+  /** How many times Den relaunched it from a handoff. */
+  rotations?: number;
   session?: SessionInfo;
 }
 
-function rowState(rec: AgentRecord | undefined, s?: SessionInfo): string {
+/** Its state as a row shows it (AG-14.1: stopped, exited or interrupted). */
+export function rowState(
+  rec: AgentRecord | undefined,
+  s?: SessionInfo,
+): string {
   // Stopped (TERM sent) while its session still runs: on its way out.
   if (s && !s.exited)
     return rec?.stoppedAt && rec.stoppedAt >= s.startedAt
       ? "stopping"
       : "running";
   if (rec?.stoppedAt) return "stopped";
-  return s ? state(s) : "ended";
+  if (rec?.endedAt)
+    return rec.exitCode === undefined ? "exited" : `exited (${rec.exitCode})`;
+  // A host sees every exit of its own sessions, with its code. A session
+  // listed as ended with no code ended with an earlier host (the host
+  // loads them so: AG-3a); one not listed at all, the same. Nobody stopped
+  // it and it never exited: the host (Den, or the machine) went down.
+  if (s && s.exitCode !== undefined) return state(s);
+  return "interrupted";
+}
+
+/** A state an agent can be removed or resumed in: not running. */
+export function isStoppedState(st: string): boolean {
+  return st !== "running" && st !== "stopping";
+}
+
+/**
+ * Why `rec` can't be resumed (AG-14.2), or null when it can be: its
+ * runtime can't resume a conversation, or has no token to resume with.
+ */
+export function resumeRefusal(rec: AgentRecord): string | null {
+  const rt = getRuntime(rec.runtime);
+  if (!rt?.resume) return `${rec.runtime} can't resume a conversation`;
+  if (!rec.resumeToken) return `${rec.id} has no conversation to resume`;
+  return null;
 }
 
 /** Whether `rec` may be resumed now, in `rowState`. */
 function canResume(rec: AgentRecord, st: string): boolean {
-  return (
-    st !== "running" &&
-    st !== "stopping" &&
-    Boolean(getRuntime(rec.runtime)?.resume)
-  );
+  return isStoppedState(st) && resumeRefusal(rec) === null;
+}
+
+/** Why a rotated agent isn't resumed: its conversation ended there (den#4). */
+export function rotatedRefusal(rec: AgentRecord, r: RotationInfo): string {
+  return `${rec.id} rotated (${reasonText(r.due!, r.compactions)}): relaunch it from its handoff`;
 }
 
 export function agentRows(
   sessions: SessionInfo[],
   records: AgentRecord[] = [],
+  /** Den's state dir: each agent's rotation is read there (den#4). */
+  stateDir?: string,
 ): AgentRow[] {
   const bySession = new Map(records.map((r) => [r.session.id, r]));
   const rows: AgentRow[] = [];
   const shown = new Set<string>();
   const row = (rec: AgentRecord, s?: SessionInfo): AgentRow => {
     const st = rowState(rec, s);
+    const rot = stateDir ? rotationInfo(stateDir, rec) : null;
+    // A rotated conversation is not resumed: it relaunches from its handoff.
+    const resumable = canResume(rec, st) && !rot?.ready;
+    const why =
+      isStoppedState(st) && !resumable
+        ? (resumeRefusal(rec) ?? (rot?.ready ? rotatedRefusal(rec, rot) : null))
+        : null;
     return {
       agent: rec.id,
       ...recordFields(rec),
       state: st,
       startedAt: s?.startedAt ?? rec.startedAt,
-      resumable: canResume(rec, st),
+      resumable,
+      ...(why ? { noResume: why } : {}),
+      ...(rec.stoppedAt ? { stoppedAt: rec.stoppedAt } : {}),
+      ...(rec.endedAt ? { endedAt: rec.endedAt } : {}),
+      ...(rec.interruptedAt ? { interruptedAt: rec.interruptedAt } : {}),
+      ...(rec.outcome ? { outcome: rec.outcome } : {}),
+      ...(rec.usage ? { usage: rec.usage } : {}),
+      ...(rot ? { rotation: rot } : {}),
+      ...(rec.rotations?.length ? { rotations: rec.rotations.length } : {}),
       ...(s ? { session: contractInfo(s) } : {}),
     };
   };
@@ -388,6 +497,28 @@ function recordFields(rec: AgentRecord): Partial<AgentRow> {
   };
 }
 
+/**
+ * Note in each record whose session the host lists as exited that it
+ * ended, with its code (AG-14.1: "Exited (code n)"), so it still says so
+ * once the host forgets the session (a restart). Only what the host says.
+ */
+export function noteEnded(
+  stateDir: string,
+  sessions: SessionInfo[],
+  records: AgentRecord[],
+): void {
+  const byId = new Map(sessions.map((s) => [s.ref.id, s]));
+  for (const rec of records) {
+    const s = byId.get(rec.session.id);
+    // An exit with no code is a host that went down: interrupted, not ended.
+    if (!s?.exited || s.exitCode === undefined) continue;
+    if (rec.endedAt || rec.stoppedAt) continue;
+    rec.endedAt = new Date().toISOString();
+    rec.exitCode = s.exitCode;
+    writeRecord(stateDir, rec);
+  }
+}
+
 /** A workspace name as given, checked (a usage error otherwise). */
 export function checkWorkspaceName(where: string, ws: unknown): string {
   if (typeof ws !== "string" || !WORKSPACE_NAME_RE.test(ws))
@@ -403,7 +534,7 @@ export function checkWorkspaceName(where: string, ws: unknown): string {
 export async function listAgents(
   d: AgentsResolved,
   ws: string,
-  opts: { startHost?: boolean } = {},
+  opts: { startHost?: boolean; stopped?: boolean } = {},
 ): Promise<AgentRow[]> {
   checkWorkspaceName("agents list", ws);
   let all: SessionInfo[];
@@ -417,7 +548,9 @@ export async function listAgents(
   } else all = await withClient(d, (c) => c.list());
   const sessions = all.filter((s) => inWorkspace(s, d.dist, ws));
   const records = listRecords(d.stateDir()).filter((r) => r.workspace === ws);
-  return agentRows(sessions, records);
+  noteEnded(d.stateDir(), sessions, records);
+  const rows = agentRows(sessions, records, d.stateDir());
+  return opts.stopped ? rows.filter((r) => isStoppedState(r.state)) : rows;
 }
 
 // ── personas, runtimes ──────────────────────────────────────────────────────
@@ -804,17 +937,26 @@ async function startSession(
     ...launch.rec,
     session: { backend: info.ref.backend, id: info.ref.id },
     startedAt: info.startedAt,
+    grants: [...launch.grants],
     ...extra,
   };
+  // A new session: whatever ended the last one no longer applies.
   delete rec.stoppedAt;
+  delete rec.endedAt;
+  delete rec.exitCode;
+  delete rec.interruptedAt;
   writeRecord(d.stateDir(), rec);
   return { rec, info };
 }
 
-/** CSI, OSC (BEL or ST ended), and other two-byte escapes. */
+/**
+ * CSI, OSC (BEL or ST ended), charset designations (`ESC ( B`), and other
+ * two-byte escapes, save and restore (`ESC 7`, `ESC 8`) and keypad modes
+ * included: Claude Code ends with `ESC ( B ESC 7 ESC 8`.
+ */
 /* eslint-disable no-control-regex */
 const TERMINAL_ESCAPE =
-  /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
+  /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[()*+\-./][ -~]|\x1b[0-9:;<=>?@-Z\\-_]/g;
 /* eslint-enable no-control-regex */
 
 /** Printable lines of terminal output: escapes and control bytes removed. */
@@ -836,6 +978,8 @@ export interface EarlyExit {
   exitCode?: number;
   /** Its last printed lines, secret-shaped values redacted. */
   tail: string[];
+  /** All it printed (the last 64 KB), as plain text, to match against. */
+  said: string;
   sessionName: string;
 }
 
@@ -857,14 +1001,14 @@ async function exitedAtOnce(
     if (!s) return null;
     if (!s.exited) continue;
     if (s.exitCode === 0) return null;
-    const tail = plainLines(
+    const lines = plainLines(
       (await c.scrollback(s.ref.id, 64 * 1024)).toString("utf-8"),
-    )
-      .slice(-EXIT_TAIL_LINES)
-      .map((l) => redactSecrets(l));
+    );
+    const tail = lines.slice(-EXIT_TAIL_LINES).map((l) => redactSecrets(l));
     return {
       ...(s.exitCode === undefined ? {} : { exitCode: s.exitCode }),
       tail,
+      said: lines.join("\n"),
       sessionName: s.name,
     };
   }
@@ -879,8 +1023,10 @@ function launchInput(
   id: string,
   model: string | undefined,
   bin?: string,
+  /** The grants to serve (a resume's, narrowed); default the config's. */
+  only?: readonly string[],
 ): LaunchInput {
-  const grants = cfg.agents[id]?.grants ?? [];
+  const grants = only ? [...only] : (cfg.agents[id]?.grants ?? []);
   for (const g of grants)
     if (!d.workspaceExists(g))
       throw refused(
@@ -891,6 +1037,10 @@ function launchInput(
   const dir = d.workspaceDir(ws);
   if (!fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory())
     throw refused(`workspace ${ws}'s directory ${dir} does not exist`);
+  // den#4: only Den's hooks count compactions; without them, no rotation.
+  const after = persona.guardrails?.hooks
+    ? rotateAfter(cfg.rotate ?? DEFAULT_ROTATE, persona)
+    : 0;
   return {
     persona,
     workspace: { name: ws, dir },
@@ -902,9 +1052,15 @@ function launchInput(
     stateDir: d.stateDir(),
     env: d.env,
     ...(bin ? { bin } : {}),
+    rotateAfter: after,
   };
 }
 
+/** The rotation limit a launch counts against: 0 when its runtime can't relaunch. */
+function launchAfter(rt: Runtime, input: LaunchInput): number {
+  return rt.firstPrompt ? (input.rotateAfter ?? 0) : 0;
+}
+
 function ptyOrRefuse(d: AgentsResolved): void {
   const pty = d.pty();
   if (!pty.available)
@@ -942,9 +1098,18 @@ export interface StartRequest {
   id?: string;
 }
 
+/** What a relaunch from handoff adds to a start (den#4). */
+interface StartMore {
+  firstPrompt?: string;
+  rotations?: AgentRecord["rotations"];
+  /** Called once the old session is known ended, before the launch. */
+  beforeLaunch?: () => void;
+}
+
 export async function startAgent(
   d: AgentsResolved,
   req: StartRequest,
+  more: StartMore = {},
 ): Promise<Started> {
   const where = "agents start";
   const ws = checkWorkspaceName(where, req.workspace);
@@ -970,7 +1135,10 @@ export async function startAgent(
       `agent ${id} belongs to workspace ${prev.workspace}; give this one another --id`,
     );
   ptyOrRefuse(d);
-  const input = launchInput(d, cfg, persona, ws, id, model, det.path);
+  const input = {
+    ...launchInput(d, cfg, persona, ws, id, model, det.path),
+    ...(more.firstPrompt ? { firstPrompt: more.firstPrompt } : {}),
+  };
 
   return withClient(d, async (c) => {
     const sessions = await c.list();
@@ -980,7 +1148,17 @@ export async function startAgent(
         `Attach: ${d.cli} sessions attach ${old.name}`,
       ]);
     const out = launchOrThrow(() => rt.launch(input));
+    more.beforeLaunch?.();
+    // A new conversation: a handoff left from the last one is kept aside,
+    // so the next rotation needs its own (den#4).
+    if (fs.existsSync(handoffFile(input.filesDir)))
+      archiveHandoff(
+        input.filesDir,
+        `${new Date().toISOString().replace(/[:.]/g, "-")}-unused`,
+      );
     writeRuntimeFiles(input.filesDir, out.files);
+    // den#4: a new conversation's compactions count from 0.
+    launchRotation(input.filesDir, out.resumeToken, launchAfter(rt, input));
     const { rec, info } = await startSession(
       d,
       c,
@@ -993,7 +1171,10 @@ export async function startAgent(
           workspace: ws,
           cwd: input.worktree,
           sessionName: sessionName(d.dist, ws, id),
-          ...(out.resumeToken ? { resumeToken: out.resumeToken } : {}),
+          // 0.4.8: launched on this token, so a resume continues it.
+          ...(out.resumeToken
+            ? { resumeToken: out.resumeToken, launched: true }
+            : {}),
         },
         argv: out.argv,
         env: out.env,
@@ -1002,7 +1183,7 @@ export async function startAgent(
         ...binDirOf(det),
       },
       old,
-      {},
+      more.rotations?.length ? { rotations: more.rotations } : {},
     );
     const early = await exitedAtOnce(d, c, info);
     return { rec, info, warnings: out.warnings ?? [], early };
@@ -1035,22 +1216,49 @@ export interface Stopped {
   rec: AgentRecord;
   /** The session it sent TERM to; undefined when it wasn't running. */
   session?: SessionInfo;
+  /** Its session was still running when the wait ran out. */
+  stillStopping?: boolean;
 }
 
+/**
+ * Stop: TERM to the agent's session, then wait (up to d.stopWaitMs) until
+ * the session has ended, so a resume right after it never finds the agent
+ * still running. Still running at the bound: `stillStopping`. With
+ * `wait: false` (or d.stopWaitMs 0) it returns once TERM is sent.
+ */
 export async function stopAgent(
   d: AgentsResolved,
   id: string,
   ws?: string,
+  opts: { wait?: boolean } = {},
 ): Promise<Stopped> {
   const rec = agentRecord(d, id, ws);
   return withClient(d, async (c) => {
     const s = sessionOf(await c.list(), rec);
     // Its token stops working before the session is asked to end.
     revokeAgentTokens(d.stateDir(), rec.id);
-    if (s && !s.exited) await c.kill(s.ref.id, "TERM");
+    const live = Boolean(s && !s.exited);
+    if (live) await c.kill(s!.ref.id, "TERM");
     const next = { ...rec, stoppedAt: new Date().toISOString() };
     writeRecord(d.stateDir(), next);
-    return { rec: next, ...(s && !s.exited ? { session: s } : {}) };
+    let stillStopping = false;
+    if (live && opts.wait !== false && d.stopWaitMs > 0) {
+      const deadline = Date.now() + d.stopWaitMs;
+      for (;;) {
+        const now = (await c.list()).find((x) => x.ref.id === s!.ref.id);
+        if (!now || now.exited) break;
+        if (Date.now() >= deadline) {
+          stillStopping = true;
+          break;
+        }
+        await new Promise((r) => setTimeout(r, EXIT_POLL_MS));
+      }
+    }
+    return {
+      rec: next,
+      ...(live ? { session: s! } : {}),
+      ...(stillStopping ? { stillStopping } : {}),
+    };
   });
 }
 
@@ -1059,6 +1267,20 @@ export interface Resumed extends Started {
   fresh: boolean;
 }
 
+/**
+ * The grants a resume serves (AG-14): the ones the agent had, never more
+ * than agents.<id>.grants gives now (a grant taken out of the config is
+ * gone). A record from before 0.4.8 has none noted: the config's.
+ */
+export function resumeGrants(
+  rec: AgentRecord,
+  cfg: ResolvedAgentsConfig,
+): string[] {
+  const now = cfg.agents[rec.id]?.grants ?? [];
+  if (!rec.grants) return [...now];
+  return rec.grants.filter((g) => now.includes(g));
+}
+
 export async function resumeAgent(
   d: AgentsResolved,
   id: string,
@@ -1067,11 +1289,28 @@ export async function resumeAgent(
   const rec = agentRecord(d, id, ws);
   syncCatalog(d);
   const rt = runtimeFor(rec.runtime);
-  if (!rt.resume)
-    throw refused(`runtime ${rt.id} does not declare resume`, [
-      `Start it again: ${d.cli} agents start -w ${rec.workspace} --persona ${rec.persona} --id ${rec.id}`,
+  // AG-14.2: never a resume that would start a new conversation instead.
+  const why = resumeRefusal(rec);
+  if (why)
+    throw refused(why, [
+      `Start fresh: ${d.cli} agents start -w ${rec.workspace} --persona ${rec.persona} --id ${rec.id}`,
     ]);
+  // den#4: a rotated conversation ends there; its role relaunches from
+  // the handoff, in a fresh one.
+  const rot = rotationInfo(d.stateDir(), rec);
+  if (rot?.ready)
+    throw new AgentError(
+      `agent ${rec.id} rotated after ${reasonText(rot.due!, rot.compactions)}: its conversation is not resumed`,
+      {
+        code: "rotated",
+        hints: [
+          `Relaunch from handoff: ${d.cli} agents relaunch ${rec.id}`,
+          `Start fresh: ${d.cli} agents start -w ${rec.workspace} --persona ${rec.persona} --id ${rec.id}`,
+        ],
+      },
+    );
   const cfg = agentsConfig(d);
+  const grants = resumeGrants(rec, cfg);
   const persona = personas(d, cfg).get(rec.persona);
   if (!persona)
     throw refused(`agent ${rec.id}'s persona "${rec.persona}" is gone`);
@@ -1091,6 +1330,7 @@ export async function resumeAgent(
       rec.id,
       rec.model,
       det.path,
+      grants,
     );
     // Resume in the cwd the agent had, wherever the workspace points now.
     const at = {
@@ -1098,29 +1338,416 @@ export async function resumeAgent(
       worktree: rec.cwd,
       ...(rec.resumeToken ? { resumeToken: rec.resumeToken } : {}),
     };
-    // A session nobody prompted left no conversation: continuing it fails,
-    // so it starts afresh under the same id. A session the host no longer
-    // lists is assumed prompted.
-    const fresh = Boolean(old && !old.prompted && rec.resumeToken);
-    const out = launchOrThrow(() => (fresh ? rt.launch(at) : rt.resume!(at)));
-    if (!out) throw refused(`agent ${rec.id} has nothing to resume`);
-    writeRuntimeFiles(input.filesDir, out.files);
+    // 0.4.8: the runtime's own resume first, whenever this token was
+    // launched (the record says so), its conversation is on disk, the last
+    // session was prompted, or the host no longer lists it. Only a record
+    // from before 0.4.8 whose session nobody prompted starts afresh under
+    // the same id.
+    const token = rec.resumeToken;
+    // A runtime that can tell (den-claude: its transcript) decides before
+    // launching: a conversation on disk, or a last session someone typed
+    // into, resumes; neither starts fresh at once. Without that, the record
+    // decides: launched on this token, or a session the host lost.
+    const known = rt.conversationExists
+      ? Boolean(token && rt.conversationExists(token, d.env)) ||
+        Boolean(old?.prompted)
+      : Boolean(rec.launched) || !old || Boolean(old.prompted);
+    const launchAs = (asFresh: boolean) => {
+      const out = launchOrThrow(() =>
+        asFresh ? rt.launch(at) : rt.resume!(at),
+      );
+      if (!out) throw refused(`agent ${rec.id} has nothing to resume`);
+      writeRuntimeFiles(input.filesDir, out.files);
+      // den#4: the same conversation keeps its count.
+      launchRotation(input.filesDir, token, launchAfter(rt, input));
+      return out;
+    };
     const { session: _s, startedAt: _t, resumedAt: _r, ...base } = rec;
-    const { rec: next, info } = await startSession(
-      d,
-      c,
-      {
-        rec: { ...base, cwd: rec.cwd },
-        argv: out.argv,
-        env: out.env,
-        passthrough: rt.envPassthrough,
-        grants: cfg.agents[rec.id]?.grants ?? [],
-        ...binDirOf(det),
-      },
-      old,
-      fresh ? {} : { resumedAt: new Date().toISOString() },
+    const run = async (asFresh: boolean, prior: SessionInfo | undefined) => {
+      const out = launchAs(asFresh);
+      const { rec: next, info } = await startSession(
+        d,
+        c,
+        {
+          rec: { ...base, cwd: rec.cwd, ...(token ? { launched: true } : {}) },
+          argv: out.argv,
+          env: out.env,
+          passthrough: rt.envPassthrough,
+          grants,
+          ...binDirOf(det),
+        },
+        prior,
+        asFresh ? {} : { resumedAt: new Date().toISOString() },
+      );
+      const early = await exitedAtOnce(d, c, info);
+      return { out, next, info, early };
+    };
+    let fresh = !known && Boolean(token);
+    let r = await run(fresh, old);
+    // It exited at once saying the other way was the right one: try that,
+    // once. A resume with nothing to continue starts fresh under the same
+    // id; a fresh start whose id is taken resumes it.
+    const said = r.early?.said ?? "";
+    const other = fresh
+      ? rt.launchFailures?.idInUse?.test(said)
+      : rt.launchFailures?.noConversation?.test(said);
+    if (r.early && other && token) {
+      const first = r;
+      fresh = !fresh;
+      // The first try's token goes with its session.
+      revokeAgentTokens(d.stateDir(), rec.id);
+      r = await run(
+        fresh,
+        (await c.list()).find((x) => x.ref.id === first.info.ref.id),
+      );
+      if (r.early)
+        throw new AgentError(
+          `agent ${rec.id}: conversation ${token} could not be continued or started (${rt.id} exited at once both ways: ${[...first.early!.tail, ...r.early.tail].slice(-4).join(" / ") || "no output"})`,
+          {
+            status: 502,
+            code: "resume_failed",
+            hints: [
+              `Start fresh: ${d.cli} agents start -w ${rec.workspace} --persona ${rec.persona} --id ${rec.id} (a new conversation)`,
+            ],
+          },
+        );
+    }
+    return {
+      rec: r.next,
+      info: r.info,
+      warnings: r.out.warnings ?? [],
+      early: r.early,
+      fresh,
+    };
+  });
+}
+
+// ── AG-14: start fresh, remove, restart ─────────────────────────────────────
+
+/**
+ * A new conversation for agent `id` (AG-14.1 Start fresh): the same
+ * persona, runtime, model and workspace, under the same id. Its last
+ * conversation stays in the runtime's own history.
+ */
+export async function startFresh(
+  d: AgentsResolved,
+  id: string,
+  ws?: string,
+): Promise<Started> {
+  const rec = agentRecord(d, id, ws);
+  return startAgent(d, {
+    workspace: rec.workspace,
+    persona: rec.persona,
+    runtime: rec.runtime,
+    ...(rec.model ? { model: rec.model } : {}),
+    id: rec.id,
+  });
+}
+
+// ── den#4: relaunch from handoff ────────────────────────────────────────────
+
+export interface Relaunched extends Started {
+  /** Why the last session rotated: "3 compactions", "PR merged". */
+  why: string;
+  /** Where its handoff was kept. */
+  handoff: string;
+}
+
+/**
+ * Relaunch from handoff (den#4): once agent `id`'s session rotated (a
+ * trigger fired and handoff.md passes the check), a fresh conversation
+ * with the same persona, runtime, model, workspace, folder and grants,
+ * whose first prompt is the handoff. A running session is stopped first.
+ * The handoff moves to handoffs/ so the next rotation needs a new one.
+ * Missing or failing: refused, saying so, with Start fresh and Resume.
+ */
+export async function relaunchAgent(
+  d: AgentsResolved,
+  id: string,
+  ws?: string,
+): Promise<Relaunched> {
+  const rec = agentRecord(d, id, ws);
+  syncCatalog(d);
+  const rt = runtimeFor(rec.runtime);
+  const files = agentFilesDir(d.stateDir(), rec.id);
+  const rot = rotationInfo(d.stateDir(), rec);
+  const fresh = `Start fresh: ${d.cli} agents start -w ${rec.workspace} --persona ${rec.persona} --id ${rec.id}`;
+  const resume = `Resume: ${d.cli} agents resume ${rec.id}`;
+  if (!rt.firstPrompt)
+    throw refused(`${rec.runtime} can't start a conversation from a handoff`, [
+      fresh,
+    ]);
+  if (!rot?.due)
+    throw refused(`agent ${rec.id} has not rotated: resume it instead`, [
+      resume,
+    ]);
+  const h = readHandoff(files);
+  if (h.status !== "ok")
+    throw new AgentError(
+      h.status === "missing"
+        ? `agent ${rec.id} has no handoff.md yet, so it can't relaunch from one`
+        : `agent ${rec.id}'s handoff.md is not ready: ${h.problems.join(" ")}`,
+      { code: "no_handoff", hints: [fresh, resume] },
     );
-    const early = await exitedAtOnce(d, c, info);
-    return { rec: next, info, warnings: out.warnings ?? [], early, fresh };
+  // The rotated session ends here, if it is still open.
+  const s = sessionOf(await hostSessions(d), rec);
+  if (s && !s.exited) {
+    const stopped = await stopAgent(d, rec.id, ws);
+    if (stopped.stillStopping)
+      throw refused(`agent ${rec.id} is still stopping; try again`);
+  }
+  const now = new Date().toISOString();
+  const why = reasonText(rot.due, rot.compactions);
+  const entry = {
+    at: now,
+    reason: rot.due,
+    compactions: rot.compactions,
+    ...(rec.resumeToken ? { conversation: rec.resumeToken } : {}),
+  };
+  let kept = "";
+  const before = readRotation(files);
+  // The launch failed: the handoff and the rotation are as they were, for
+  // the conversation the record now names, so Relaunch is offered again.
+  const undo = (conversation?: string) => {
+    if (kept && fs.existsSync(kept) && !fs.existsSync(handoffFile(files)))
+      fs.renameSync(kept, handoffFile(files));
+    if (before)
+      writeRotation(files, {
+        ...before,
+        due: rot.due,
+        ...(conversation ? { conversation } : {}),
+      });
+  };
+  const started = await startAgent(
+    d,
+    {
+      workspace: rec.workspace,
+      persona: rec.persona,
+      runtime: rec.runtime,
+      ...(rec.model ? { model: rec.model } : {}),
+      id: rec.id,
+    },
+    {
+      firstPrompt: handoffPrompt(h.text!, rot.due, rot.compactions),
+      rotations: [...(rec.rotations ?? []), entry],
+      beforeLaunch: () => {
+        kept = archiveHandoff(
+          files,
+          `${now.replace(/[:.]/g, "-")}-${rec.resumeToken ?? "conversation"}`,
+        );
+      },
+    },
+  ).catch((e: unknown) => {
+    undo();
+    throw e;
   });
+  if (started.early) undo(started.rec.resumeToken);
+  return { ...started, why, handoff: kept };
+}
+
+/** The host's sessions, never starting a host (none running: none). */
+async function hostSessions(d: AgentsResolved): Promise<SessionInfo[]> {
+  const c = await d.connectExisting();
+  try {
+    return c ? await c.list() : [];
+  } finally {
+    c?.close();
+  }
+}
+
+/** An agent removed (AG-14.1b): what Undo brings back. */
+export interface Removed {
+  agent: string;
+  workspace: string;
+}
+
+/**
+ * Forget agents `ids` (AG-14.1b): each record moves aside for Undo, its
+ * actor tokens are revoked and the host forgets its ended session. A
+ * running agent is refused: stop it first. Never asks a host to start.
+ */
+async function removeRecords(
+  d: AgentsResolved,
+  recs: AgentRecord[],
+): Promise<Removed[]> {
+  const c = await d.connectExisting();
+  try {
+    const sessions = c ? await c.list() : [];
+    for (const rec of recs) {
+      const s = sessionOf(sessions, rec);
+      if (!isStoppedState(rowState(rec, s)))
+        throw refused(`agent ${rec.id} is running: stop it first`, [
+          `${d.cli} agents stop ${rec.id}`,
+        ]);
+    }
+    const out: Removed[] = [];
+    for (const rec of recs) {
+      const s = sessionOf(sessions, rec);
+      revokeAgentTokens(d.stateDir(), rec.id);
+      if (c && s?.exited) await c.forget(s.ref.id).catch(() => undefined);
+      if (removeRecord(d.stateDir(), rec.id))
+        out.push({ agent: rec.id, workspace: rec.workspace });
+    }
+    purgeRemoved(d.stateDir());
+    return out;
+  } finally {
+    c?.close();
+  }
+}
+
+export async function removeAgent(
+  d: AgentsResolved,
+  id: string,
+  ws?: string,
+): Promise<Removed[]> {
+  return removeRecords(d, [agentRecord(d, id, ws)]);
+}
+
+/**
+ * Remove every stopped, interrupted or exited agent of `workspaces`
+ * (AG-14.1b Clear stopped); running ones stay.
+ */
+export async function removeStopped(
+  d: AgentsResolved,
+  workspaces: readonly string[],
+): Promise<Removed[]> {
+  const sessions = await hostSessions(d);
+  const recs = listRecords(d.stateDir()).filter(
+    (r) =>
+      workspaces.includes(r.workspace) &&
+      isStoppedState(rowState(r, sessionOf(sessions, r))),
+  );
+  return removeRecords(d, recs);
+}
+
+/** Undo: bring removed agents back; the ones that came back. */
+export function restoreAgents(
+  d: AgentsResolved,
+  ids: readonly string[],
+): string[] {
+  return ids.filter((id) => restoreRecord(d.stateDir(), id));
+}
+
+/**
+ * Forget stopped and exited agents older than `days` (AG-14.1b,
+ * agents.remove_stopped_after in user.yml; 0: never). Interrupted ones
+ * are never forgotten. Returns the ids forgotten.
+ */
+export async function pruneStopped(
+  d: AgentsResolved,
+  days: number,
+  now = Date.now(),
+): Promise<string[]> {
+  if (!(days > 0)) return [];
+  const sessions = await hostSessions(d);
+  const cutoff = now - days * 86_400_000;
+  const old = listRecords(d.stateDir()).filter((r) => {
+    const st = rowState(r, sessionOf(sessions, r));
+    if (st === "interrupted" || !isStoppedState(st)) return false;
+    const at = Date.parse(r.stoppedAt ?? r.endedAt ?? r.startedAt);
+    return Number.isFinite(at) && at < cutoff;
+  });
+  for (const r of old) {
+    revokeAgentTokens(d.stateDir(), r.id);
+    removeRecord(d.stateDir(), r.id);
+  }
+  purgeRemoved(d.stateDir(), 0, now);
+  return old.map((r) => r.id);
+}
+
+/** What a restart found (AG-14.3). */
+export interface RestartFound {
+  /** Agents newly marked interrupted. */
+  interrupted: string[];
+  /** Of those, the ones resumed on their own (standing, resume_on_restart). */
+  resumed: string[];
+  /** Ones that should have resumed but couldn't, with why. */
+  failed: { agent: string; why: string }[];
+}
+
+/**
+ * When the web server starts (AG-14.3): every agent whose session is gone
+ * though nobody stopped it and it never exited is marked interrupted. A
+ * session host that survived a web-server-only restart still lists its
+ * sessions, so nothing is marked. Then the standing personas, and those
+ * with `resume_on_restart: true`, resume (when their runtime can); the
+ * rest wait for someone to click Resume.
+ */
+export async function markInterrupted(
+  d: AgentsResolved,
+  opts: { autoResume?: boolean } = {},
+): Promise<RestartFound> {
+  const sessions = await hostSessions(d);
+  const found: RestartFound = { interrupted: [], resumed: [], failed: [] };
+  const now = new Date().toISOString();
+  const marked: AgentRecord[] = [];
+  for (const rec of listRecords(d.stateDir())) {
+    if (rec.interruptedAt) continue;
+    if (rowState(rec, sessionOf(sessions, rec)) !== "interrupted") continue;
+    const next = { ...rec, interruptedAt: now };
+    writeRecord(d.stateDir(), next);
+    marked.push(next);
+    found.interrupted.push(rec.id);
+  }
+  if (opts.autoResume === false || !marked.length) return found;
+  let all: Map<string, Persona>;
+  try {
+    all = personas(d, agentsConfig(d));
+  } catch {
+    return found;
+  }
+  for (const rec of marked) {
+    const p = all.get(rec.persona);
+    if (!p || !(p.standing || p.resumeOnRestart)) continue;
+    if (resumeRefusal(rec)) continue;
+    try {
+      // den#4: a rotated one relaunches from its handoff instead.
+      const r = rotationInfo(d.stateDir(), rec)?.ready
+        ? await relaunchAgent(d, rec.id)
+        : await resumeAgent(d, rec.id);
+      if (r.early) found.failed.push({ agent: rec.id, why: "exited at once" });
+      else found.resumed.push(rec.id);
+    } catch (e) {
+      found.failed.push({ agent: rec.id, why: (e as Error).message });
+    }
+  }
+  return found;
+}
+
+/**
+ * Resume every interrupted agent of `workspaces` that can resume
+ * (AG-14.3 "Resume all", `agents resume --all-interrupted`).
+ */
+export async function resumeInterrupted(
+  d: AgentsResolved,
+  workspaces?: readonly string[],
+): Promise<{
+  resumed: Resumed[];
+  failed: { agent: string; why: string }[];
+}> {
+  const sessions = await hostSessions(d);
+  const recs = listRecords(d.stateDir()).filter(
+    (r) =>
+      (!workspaces || workspaces.includes(r.workspace)) &&
+      rowState(r, sessionOf(sessions, r)) === "interrupted",
+  );
+  const resumed: Resumed[] = [];
+  const failed: { agent: string; why: string }[] = [];
+  for (const rec of recs) {
+    const rot = rotationInfo(d.stateDir(), rec);
+    const why =
+      resumeRefusal(rec) ?? (rot?.ready ? rotatedRefusal(rec, rot) : null);
+    if (why) {
+      failed.push({ agent: rec.id, why });
+      continue;
+    }
+    try {
+      const r = await resumeAgent(d, rec.id);
+      if (r.early) failed.push({ agent: rec.id, why: "exited at once" });
+      else resumed.push(r);
+    } catch (e) {
+      failed.push({ agent: rec.id, why: (e as Error).message });
+    }
+  }
+  return { resumed, failed };
 }