@monster-orange/den 0.4.15 → 0.4.17

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

@@ -455,6 +455,11 @@ export interface AgentRow {
    * runtime's resume token, and it isn't running.
    */
   resumable: boolean;
+  /**
+   * AG-18: Change persona… applies: its runtime can resume and its record
+   * has a conversation to continue (running or not), not rotated.
+   */
+  personaChange?: 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.
@@ -553,6 +558,9 @@ export function agentRows(
       state: st,
       startedAt: s?.startedAt ?? rec.startedAt,
       resumable,
+      ...(!rot?.ready && !personaChangeRefusal(rec)
+        ? { personaChange: true }
+        : {}),
       ...(why ? { noResume: why } : {}),
       ...(rec.stoppedAt ? { stoppedAt: rec.stoppedAt } : {}),
       ...(rec.endedAt ? { endedAt: rec.endedAt } : {}),
@@ -1675,6 +1683,17 @@ export interface ListedConversation extends RuntimeConversation {
   open: boolean;
   /** The Den agent already continuing it, if one is. */
   agent?: string;
+  /**
+   * AG-17.1c: the persona Bring in preselects: the one of the latest Den
+   * agent that worked in its folder (or one inside it), else the
+   * workspace's latest agent's. The person confirms; never submitted.
+   */
+  suggest?: string;
+  /**
+   * AG-17.1c: the MCP servers its tools came from that Den won't load (an
+   * agent runs with Den's tools only).
+   */
+  lost?: string[];
 }
 
 /** Each runtime, and whether it can bring a conversation in. */
@@ -1729,6 +1748,7 @@ export function listConversations(
   // Its folder and every repo's; a shared root only exactly (AG-17.1).
   const scope = d.workspaceFolders(ws);
   const taken = agentByToken(d);
+  const suggestFor = personaSuggester(d, ws);
   const now = Date.now();
   const conversations: ListedConversation[] = [];
   const seen = new Set<string>();
@@ -1740,11 +1760,15 @@ export function listConversations(
       if (seen.has(`${id} ${c.id}`)) continue;
       seen.add(`${id} ${c.id}`);
       const agent = taken.get(`${id} ${c.id}`);
+      const lost = (c.mcp ?? []).filter((m) => m !== d.cli);
+      const suggest = suggestFor(c.cwd);
       conversations.push({
         ...c,
         runtime: id,
         open: openElsewhere(c.lastAt, now),
         ...(agent ? { agent } : {}),
+        ...(suggest ? { suggest } : {}),
+        ...(lost.length ? { lost } : {}),
       });
     }
   }
@@ -1752,6 +1776,36 @@ export function listConversations(
   return { runtimes: bringInRuntimes(), conversations };
 }
 
+/**
+ * AG-17.1c: the persona to preselect for a conversation that ran in a
+ * folder: the latest agent's of this workspace that worked there (or in a
+ * folder inside it), else the workspace's latest agent's; only a persona
+ * that still exists. Undefined: none to suggest (the page's first).
+ */
+function personaSuggester(
+  d: AgentsResolved,
+  ws: string,
+): (cwd: string) => string | undefined {
+  let known: Set<string>;
+  try {
+    known = new Set(personas(d, agentsConfig(d)).keys());
+  } catch {
+    return () => undefined;
+  }
+  const recs = listRecords(d.stateDir())
+    .filter((r) => r.workspace === ws && known.has(r.persona))
+    .sort((a, b) =>
+      (b.resumedAt ?? b.startedAt).localeCompare(a.resumedAt ?? a.startedAt),
+    );
+  const inside = (p: string, dir: string) => {
+    const rel = path.relative(dir, p);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+  };
+  return (cwd) =>
+    (recs.find((r) => inside(r.cwd, cwd) || inside(cwd, r.cwd)) ?? recs[0])
+      ?.persona;
+}
+
 export interface ImportRequest {
   workspace: string;
   /** The runtime's conversation id. */
@@ -1759,6 +1813,13 @@ export interface ImportRequest {
   persona: string;
   runtime?: string;
   id?: string;
+  /**
+   * AG-17.1c: a model for it (Advanced). Absent: the conversation's own
+   * (its last answer's), else the persona's.
+   */
+  model?: string;
+  /** With model: "latest" or a pinned version (AG-12.3). */
+  version?: string;
 }
 
 /** The persona's id, else the first `<persona>-<n>` no agent has. */
@@ -1831,9 +1892,23 @@ export async function importAgent(
   const id = req.id ?? freeId(d, req.persona);
   if (readRecord(d.stateDir(), id))
     throw refused(`${where}: agent ${id} exists; give this one another --id`);
+  // AG-17.1c: the conversation keeps its own model unless one is picked.
+  const model = req.model ?? c.model;
   return startAgent(
     d,
-    { workspace: req.workspace, persona: req.persona, runtime, id },
+    {
+      workspace: req.workspace,
+      persona: req.persona,
+      runtime,
+      id,
+      ...(model ? { model } : {}),
+      ...(req.model !== undefined && req.version !== undefined
+        ? { version: req.version }
+        : {}),
+      // A model picked on the page is checked against the catalog; the
+      // conversation's own is taken as it ran.
+      ...(req.model !== undefined ? { strict: true } : {}),
+    },
     { bringIn: { token: c.id, cwd: c.cwd } },
   );
 }
@@ -2113,6 +2188,234 @@ export async function resumeAgent(
   });
 }
 
+// ── AG-18: change a running agent's persona ─────────────────────────────────
+
+/** The refusal code while its turn is going and no `when` was given. */
+export const PERSONA_BUSY = "busy";
+
+export interface PersonaRequest {
+  persona: string;
+  /** Advanced: another model. Absent: the one it runs (the conversation's). */
+  model?: string;
+  /** With model: "latest" or a pinned version. */
+  version?: string;
+  /**
+   * Mid-turn: "after-turn" waits until its turn ends, "now" stops it. None:
+   * refused (PERSONA_BUSY) while it works, so a turn is never cut silently.
+   */
+  when?: "now" | "after-turn";
+  /** Who asked (a person's sign-in, "cli"), for its record. */
+  by?: string;
+}
+
+export interface PersonaChanged extends Resumed {
+  from: string;
+}
+
+/**
+ * What a resume with nothing to continue yet says (AG-14, AG-18): the
+ * runtime started fresh under the same conversation id.
+ */
+export const FRESH_NOTE =
+  "nothing to resume yet; started fresh (same conversation id, folder and scope)";
+
+/** How often, and how long, "after this turn" checks its turn (AG-18). */
+export const TURN_POLL_MS = 1_000;
+export const TURN_WAIT_MS = 30 * 60_000;
+
+/**
+ * Whether agent `rec` is mid-turn: true or false from its runtime (den-
+ * claude: its transcript), null when it can't tell. Not running: false.
+ */
+async function agentBusy(
+  d: AgentsResolved,
+  rec: AgentRecord,
+): Promise<boolean | null> {
+  const live = await withClient(d, async (c) => {
+    const s = sessionOf(await c.list(), rec);
+    return Boolean(s && !s.exited);
+  });
+  if (!live) return false;
+  const rt = getRuntime(rec.runtime);
+  if (!rt?.turnBusy || !rec.resumeToken) return null;
+  return rt.turnBusy(rec.resumeToken, d.env);
+}
+
+/** Why agent `rec` can't change persona (it can't resume), or null. */
+export function personaChangeRefusal(rec: AgentRecord): string | null {
+  const rt = getRuntime(rec.runtime);
+  if (!rt?.resume)
+    return `${rt?.label ?? rec.runtime} can't continue a conversation, so it can't change persona`;
+  return resumeRefusal(rec);
+}
+
+/**
+ * AG-18, change persona: Den stops the agent's session and resumes the
+ * same conversation with the new persona's launch settings (its role
+ * prompt, permission mode, allowed commands). The history stays; so do the
+ * id, name, workspace, folder and grants, and the model it runs unless
+ * one is given. Mid-turn it never stops a turn unasked: refused with
+ * PERSONA_BUSY, or `when` says to wait for the turn's end or stop now.
+ * Only a runtime that can resume can. The person's only: callers refuse an
+ * agent's token before this.
+ */
+export async function changePersona(
+  d: AgentsResolved,
+  id: string,
+  ws: string | undefined,
+  req: PersonaRequest,
+  opts: { pollMs?: number; maxMs?: number } = {},
+): Promise<PersonaChanged> {
+  const where = "agents persona";
+  const rec = agentRecord(d, id, ws);
+  const cfg = agentsConfig(d);
+  const all = personas(d, cfg);
+  if (!all.get(req.persona))
+    throw usage(
+      `${where}: no persona "${req.persona}" (personas: ${[...all.keys()].sort().join(", ")})`,
+    );
+  if (req.persona === rec.persona && req.model === undefined)
+    throw usage(`${where}: agent ${rec.id} is already ${rec.persona}`);
+  const why = personaChangeRefusal(rec);
+  if (why) throw refused(why, [], 422);
+  let busy = await agentBusy(d, rec);
+  if (busy !== false && req.when === undefined)
+    throw new AgentError(
+      busy
+        ? `agent ${rec.id} is working. Change after this turn, or stop it now?`
+        : `agent ${rec.id} is running and Den can't tell whether it is mid-turn. Change after this turn, or stop it now?`,
+      {
+        status: 409,
+        code: PERSONA_BUSY,
+        hints: [
+          `After this turn: ${d.cli} agents persona ${rec.id} ${req.persona} --after-turn`,
+          `Stop it now: ${d.cli} agents persona ${rec.id} ${req.persona} --now`,
+        ],
+      },
+    );
+  if (busy === null && req.when === "after-turn")
+    throw refused(
+      `${where}: Den can't tell when agent ${rec.id}'s turn ends; stop it now instead (--now)`,
+    );
+  if (req.when !== "after-turn") return switchPersona(d, rec, req, where);
+  // Waiting: marked on the record, so a restart that drops the wait can
+  // say so (cancelStalePersonaChanges); cleared however this ends.
+  writeRecord(d.stateDir(), {
+    ...rec,
+    pendingPersona: {
+      to: req.persona,
+      since: new Date().toISOString(),
+      ...(req.by ? { by: req.by } : {}),
+    },
+  });
+  try {
+    const deadline = Date.now() + (opts.maxMs ?? TURN_WAIT_MS);
+    while (busy) {
+      if (Date.now() >= deadline)
+        throw refused(
+          `${where}: agent ${rec.id} was still working after ${Math.round((opts.maxMs ?? TURN_WAIT_MS) / 60_000)} min; nothing changed`,
+        );
+      await new Promise((r) => setTimeout(r, opts.pollMs ?? TURN_POLL_MS));
+      busy = await agentBusy(d, agentRecord(d, id, ws));
+    }
+    return await switchPersona(d, rec, req, where);
+  } catch (e) {
+    clearPendingPersona(d, rec.id);
+    throw e;
+  }
+}
+
+/** Drop agent `id`'s pending persona change mark, if it has one. */
+function clearPendingPersona(d: AgentsResolved, id: string): void {
+  const cur = readRecord(d.stateDir(), id);
+  if (!cur?.pendingPersona) return;
+  const { pendingPersona: _pp, ...rest } = cur;
+  writeRecord(d.stateDir(), rest);
+}
+
+/**
+ * At start (AG-18): every persona change still marked pending was dropped
+ * when Den stopped, since the wait lived in memory. Clears each mark and
+ * returns them, for the audit trail.
+ */
+export function cancelStalePersonaChanges(d: AgentsResolved): {
+  id: string;
+  workspace: string;
+  from: string;
+  to: string;
+  by?: string;
+}[] {
+  const out: ReturnType<typeof cancelStalePersonaChanges> = [];
+  for (const rec of listRecords(d.stateDir())) {
+    const p = rec.pendingPersona;
+    if (!p) continue;
+    clearPendingPersona(d, rec.id);
+    out.push({
+      id: rec.id,
+      workspace: rec.workspace,
+      from: rec.persona,
+      to: p.to,
+      ...(p.by ? { by: p.by } : {}),
+    });
+  }
+  return out;
+}
+
+/** The switch itself: stop, the new persona's settings, resume. */
+async function switchPersona(
+  d: AgentsResolved,
+  rec: AgentRecord,
+  req: PersonaRequest,
+  where: string,
+): Promise<PersonaChanged> {
+  const stopped = await stopAgent(d, rec.id, rec.workspace);
+  if (stopped.stillStopping)
+    throw refused(
+      `${where}: agent ${rec.id} is still stopping; try again in a moment`,
+    );
+  // The new persona's permissions apply: the old one's choices go. The
+  // model stays (the conversation's) unless one is given.
+  const {
+    permission: _p,
+    allow: _a,
+    overrides: _o,
+    pendingPersona: _pp,
+    ...base
+  } = stopped.rec;
+  const keptOverrides = (rec.overrides ?? []).filter(
+    (o) => o === "runtime" || o === "model" || o === "version",
+  );
+  const next: AgentRecord = {
+    ...base,
+    persona: req.persona,
+    ...(req.model !== undefined
+      ? { model: req.model, version: req.version ?? "latest" }
+      : {}),
+    ...(keptOverrides.length || req.model !== undefined
+      ? {
+          overrides: [
+            ...new Set([
+              ...keptOverrides,
+              ...(req.model !== undefined ? (["model"] as const) : []),
+            ]),
+          ],
+        }
+      : {}),
+    personaChanges: [
+      ...(rec.personaChanges ?? []),
+      {
+        from: rec.persona,
+        to: req.persona,
+        at: new Date().toISOString(),
+        ...(req.by ? { by: req.by } : {}),
+      },
+    ],
+  };
+  writeRecord(d.stateDir(), next);
+  const r = await resumeAgent(d, rec.id, rec.workspace);
+  return { ...r, from: rec.persona };
+}
+
 // ── AG-14: start fresh, remove, restart ─────────────────────────────────────
 
 /**

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

@@ -64,6 +64,7 @@
  */
 import * as fs from "fs";
 import { DEFAULT_RUNTIME_ID } from "../../shared/agents/runtimes.js";
+import { ACTOR_TOKEN_ENV } from "../../shared/actor-token.js";
 import { initLoginPath } from "../../shared/agents/runtime-search.js";
 import { HostError } from "../../shared/sessions/client.js";
 import { checkHandback } from "../../shared/agents/handback.js";
@@ -77,6 +78,7 @@ import {
 import {
   AgentError,
   importAgent,
+  changePersona,
   listAgents,
   listConversations,
   listPersonas as personaList,
@@ -93,6 +95,7 @@ import {
   type AgentsDeps,
   type AgentsResolved,
   type EarlyExit,
+  FRESH_NOTE,
   type RuntimeChoice,
   type Started,
 } from "./agent-ops.js";
@@ -116,7 +119,7 @@ export {
 
 export const AGENTS_HELP = {
   usage:
-    "agents <list|start|stop|resume|relaunch|import|rm|personas|doctor|handback-check|handoff-check> ...",
+    "agents <list|start|stop|resume|relaunch|import|persona|rm|personas|doctor|handback-check|handoff-check> ...",
   lines: [
     "Agents: a persona and a workspace, run by a runtime in a session that",
     "outlives the web server (see `{cli} sessions`).",
@@ -142,11 +145,17 @@ export const AGENTS_HELP = {
     "    passes the check, a fresh conversation (same persona, workspace, folder,",
     "    grants) whose first prompt is the handoff",
     "{cli} agents import -w <ws> [--runtime <r>] [--json]",
-    "{cli} agents import -w <ws> --session <id> --persona <p> [--runtime <r>] [--id <id>]",
+    "{cli} agents import -w <ws> --session <id> --persona <p> [--runtime <r>] [--id <id>] [--model <m>]",
     "    bring in a conversation started outside Den: the first lists the runtime's",
     "    own (default den-claude) in the workspace's folder; the second continues",
     "    one as a Den agent (its resume, in the folder it ran in). Refused while it",
-    "    is still open in another terminal: close it there first",
+    "    is still open in another terminal: close it there first. It keeps the",
+    "    conversation's own model unless --model gives one",
+    "{cli} agents persona <id> <persona> [-w <ws>] [--model <m>] [--now | --after-turn]",
+    "    change an agent's persona: the same conversation resumes with the new",
+    "    persona's role, permissions and commands; id, name, folder and model stay.",
+    "    Mid-turn it asks: --after-turn waits for the turn to end, --now stops it.",
+    "    A person's only (refused in an agent's session)",
     "{cli} agents rm <id> [-w <ws>]",
     "{cli} agents rm --stopped [-w <ws>]",
     "    forget a stopped, interrupted or exited agent (never a running one);",
@@ -306,6 +315,8 @@ async function bringIn(args: string[], d: AgentsResolved): Promise<number> {
     "--session": true,
     "--persona": true,
     "--id": true,
+    "--model": true,
+    "--version": true,
     "--json": false,
   });
   noExtra(where, p);
@@ -355,6 +366,11 @@ async function bringIn(args: string[], d: AgentsResolved): Promise<number> {
     persona,
     runtime,
     id: str(p, "--id"),
+    // AG-17.1c: the conversation's own model unless one is given.
+    ...(str(p, "--model") !== undefined ? { model: str(p, "--model") } : {}),
+    ...(str(p, "--version") !== undefined
+      ? { version: str(p, "--version") }
+      : {}),
   });
   return report(
     d,
@@ -363,6 +379,54 @@ async function bringIn(args: string[], d: AgentsResolved): Promise<number> {
   );
 }
 
+/**
+ * `agents persona <id> <persona> [-w <ws>] [--model <m>] [--version <v>]
+ * [--now | --after-turn]` (AG-18). A person's only: refused inside an
+ * agent's session (its DEN_ACTOR_TOKEN), so an agent can't widen its own
+ * permissions.
+ */
+async function persona(args: string[], d: AgentsResolved): Promise<number> {
+  const where = "agents persona";
+  if (d.env[ACTOR_TOKEN_ENV] !== undefined)
+    throw new AgentError(
+      `${where}: only a person can change an agent's persona (this is an agent's session)`,
+    );
+  const p = parseArgs(where, args, {
+    "--workspace": true,
+    "--model": true,
+    "--version": true,
+    "--now": false,
+    "--after-turn": false,
+  });
+  noExtra(where, p, 2);
+  const [id, to] = p.positional;
+  if (!id || !to) throw new UsageError(`${where} needs <id> <persona>`);
+  if (p.flags["--now"] && p.flags["--after-turn"])
+    throw new UsageError(`${where}: --now or --after-turn, not both`);
+  const when = p.flags["--now"]
+    ? "now"
+    : p.flags["--after-turn"]
+      ? "after-turn"
+      : undefined;
+  if (when === "after-turn") d.out(`waiting for agent ${id}'s turn to end…`);
+  const s = await changePersona(d, id, workspaceFlag(where, p), {
+    persona: to,
+    ...(str(p, "--model") !== undefined ? { model: str(p, "--model") } : {}),
+    ...(str(p, "--version") !== undefined
+      ? { version: str(p, "--version") }
+      : {}),
+    ...(when ? { when } : {}),
+    by: "cli",
+  });
+  return report(
+    d,
+    s,
+    s.fresh
+      ? `agent ${s.rec.id} is now ${s.rec.persona} (was ${s.from}); ${FRESH_NOTE}, as ${s.rec.sessionName} in ${s.rec.cwd}`
+      : `agent ${s.rec.id} is now ${s.rec.persona} (was ${s.from}); same conversation, as ${s.rec.sessionName} in ${s.rec.cwd}`,
+  );
+}
+
 /** `<id> [-w <ws>]`. */
 function idAndWorkspace(
   where: string,
@@ -407,10 +471,7 @@ 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}: nothing to resume yet; started fresh (same conversation id, folder and scope)`,
-    );
+  if (s.fresh) d.out(`agent ${s.rec.id}: ${FRESH_NOTE}`);
   return report(
     d,
     s,
@@ -703,6 +764,9 @@ export async function cmdAgents(
         case "import":
           await loadAgentWorkspaces(deps);
           return await bringIn(rest, d);
+        case "persona":
+          await loadAgentWorkspaces(deps);
+          return await persona(rest, d);
         case "rm":
           await loadAgentWorkspaces(deps);
           return await rm(rest, d);

package/src/ui/server/agent-routes.ts

@@ -119,6 +119,7 @@ import {
   updatePersona,
   listRuntimes,
   markInterrupted,
+  cancelStalePersonaChanges,
   NOT_IN_WORKSPACE,
   pruneStopped,
   removeAgent,
@@ -129,6 +130,7 @@ import {
   setRuntimePath,
   resolveAgentsDeps,
   importAgent,
+  changePersona,
   listConversations,
   relaunchAgent,
   resumeAgent,
@@ -138,6 +140,7 @@ import {
   type AgentsDeps,
   type AgentsResolved,
   type Started,
+  FRESH_NOTE,
 } from "../cli/agent-ops.js";
 import { agentSessionName } from "../../shared/agents/session-name.js";
 import { recordAction } from "./audit.js";
@@ -159,10 +162,12 @@ export interface AgentRouteDeps {
   agents?: AgentsDeps;
   /** When a first instruction counts its session ready (tests: shorter). */
   instruction?: { quietMs?: number; maxMs?: number };
+  /** AG-18: how "after this turn" polls (tests: shorter). */
+  personaWait?: { pollMs?: number; maxMs?: number };
 }
 
 const AGENTS_PATH =
-  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove|name|paths))?$/;
+  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove|name|paths|persona))?$/;
 
 const RUNTIME_PATH = /^\/api\/agents\/runtimes\/([^/]+)\/path$/;
 const PERSONA_PATH = /^\/api\/personas\/([^/]+)$/;
@@ -476,6 +481,7 @@ export async function handleAgentRoutes(
     | "remove"
     | "name"
     | "paths"
+    | "persona"
     | undefined;
 
   if (!action && method === "GET") {
@@ -550,6 +556,13 @@ export async function handleAgentRoutes(
     if (id !== undefined) agentRecord(d, id, ws);
     // AG-14.4: MCP agent_resume may resume another agent of its scope.
     const agent = agentPrincipalOf(req);
+    // AG-18: a persona is the person's choice: an agent could widen its
+    // own permissions with it. Any agent credential or claim is refused.
+    if (verb === "persona" && (agent || actor))
+      throw new AgentError(
+        "only a person can change an agent's persona (an agent can't change its own or another's)",
+        { status: 403 },
+      );
     if (verb === "resume" && agent) {
       const why = agentResumeRefusal(agent, ws, id!, mcpActions());
       if (why) throw new AgentError(why, { status: 403 });
@@ -647,6 +660,64 @@ export async function handleAgentRoutes(
         agent: rec.id,
         ...(rec.displayName ? { displayName: rec.displayName } : {}),
       });
+    } else if (verb === "persona") {
+      const body = await jsonBody(req);
+      for (const k of Object.keys(body))
+        if (!PERSONA_KEYS.includes(k))
+          throw new AgentError(
+            `${k}: unknown field (a persona change takes ${PERSONA_KEYS.join(", ")})`,
+            { usage: true },
+          );
+      const str = (k: string): string | undefined => {
+        const v = body[k];
+        if (v === undefined || v === null || v === "") return undefined;
+        if (typeof v !== "string" || v.length > 128 || /[^\x21-\x7e]/.test(v))
+          throw new AgentError(`${k} must be a short name`, { usage: true });
+        return v;
+      };
+      const persona = str("persona");
+      if (!persona)
+        throw new AgentError("persona is required", { usage: true });
+      const when = str("when");
+      if (when !== undefined && when !== "now" && when !== "after-turn")
+        throw new AgentError("when must be now or after-turn", {
+          usage: true,
+        });
+      const from = agentRecord(d, id!, ws).persona;
+      const by = principalOf(req) ?? "this machine";
+      what = `persona ${id} in ${ws}: ${from} → ${persona}, by ${by}`;
+      const change = () =>
+        changePersona(
+          d,
+          id!,
+          ws,
+          {
+            persona,
+            ...(str("model") !== undefined ? { model: str("model") } : {}),
+            ...(str("version") !== undefined
+              ? { version: str("version") }
+              : {}),
+            ...(when ? { when: when as "now" | "after-turn" } : {}),
+            by,
+          },
+          deps.personaWait ?? {},
+        );
+      if (when === "after-turn") {
+        // It may wait for a long turn: answer now, audit when it's done.
+        agentRecord(d, id!, ws);
+        void change().then(
+          (s) => audit(what, s.early ? "exited at once" : undefined),
+          (e: unknown) =>
+            audit(what, e instanceof Error ? e.message : String(e)),
+        );
+        sendJson(res, { ok: true, agent: id, pending: true, persona }, 202);
+        return true;
+      }
+      const s = await change();
+      audit(what, s.early ? "exited at once" : undefined);
+      // Never prompted: nothing was resumed, so it says so (not "same
+      // conversation").
+      sendStarted(res, s, d, s.fresh ? { note: FRESH_NOTE } : {});
     } else if (verb === "remove") {
       const removed = await removeAgent(d, id!, ws);
       audit(what);
@@ -663,7 +734,9 @@ export async function handleAgentRoutes(
   return true;
 }
 
-const IMPORT_KEYS = ["persona", "runtime", "id"];
+const IMPORT_KEYS = ["persona", "runtime", "id", "model", "version"];
+/** AG-18: what a persona change takes. */
+const PERSONA_KEYS = ["persona", "model", "version", "when"];
 
 /**
  * Bring in (AG-17.1): GET lists the workspace's conversations, POST
@@ -737,6 +810,8 @@ async function conversations(
       persona,
       runtime: str("runtime"),
       id: str("id"),
+      ...(str("model") !== undefined ? { model: str("model") } : {}),
+      ...(str("version") !== undefined ? { version: str("version") } : {}),
     });
     what = `bring in ${session} as ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
     audit(s.early ? "exited at once" : undefined);
@@ -1089,6 +1164,21 @@ export function startAgentUpkeep(
 ): void {
   const d = webDeps(deps.agents);
   const restart = async () => {
+    // AG-18: a persona change waiting for a turn's end lived in memory.
+    try {
+      for (const c of cancelStalePersonaChanges(d)) {
+        const what = `persona ${c.id} in ${c.workspace}: ${c.from} → ${c.to}, by ${c.by ?? "this machine"}`;
+        recordAction(null, {
+          verb: "agents",
+          detail: what,
+          outcome: "refused",
+          reason: "persona change cancelled: Den restarted",
+        });
+        log(`Persona change cancelled (Den restarted): ${what}`);
+      }
+    } catch (e) {
+      log(`  ⚠ persona changes after the restart: ${(e as Error).message}`);
+    }
     try {
       const f = await markInterrupted(d);
       if (f.interrupted.length)