@monster-orange/den 0.4.14 → 0.4.16

package/src/shared/web-session.ts

@@ -21,7 +21,7 @@ import { createHash, createHmac, randomBytes, timingSafeEqual } from "crypto";
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "yaml";
-import { parseMachineName } from "./cli-command.js";
+import { parseMachineName, parseSshUser } from "./cli-command.js";
 import { getStateDir } from "./paths.js";
 
 export const LOGIN_CODE_TTL_MS = 60_000;
@@ -195,6 +195,12 @@ export interface WebAuthConfig {
    * page gives this machine ("runs on <name>"). Unset: the short hostname.
    */
   machineName?: string;
+  /**
+   * `web.ssh_user` (SEC-2a-UX; user.yml, else the distribution's): the
+   * account the signed-out page's ssh link logs in as. Unset: the account
+   * Den runs as. "": no account on the page.
+   */
+  sshUser?: string;
 }
 
 /** `web.edge_unattested`'s values. */
@@ -290,8 +296,13 @@ export function readWebAuthConfig(
   const clientId =
     clientIdOf(user, "config/local/user.yml") ?? clientIdOf(team, configFile);
   const machineName = parseMachineName(user.machine_name);
+  const sshUser =
+    user.ssh_user !== undefined
+      ? parseSshUser(user.ssh_user)
+      : parseSshUser(team.ssh_user);
   return {
     ...(machineName ? { machineName } : {}),
+    ...(sshUser !== undefined ? { sshUser } : {}),
     allowPlainHttpRemote: plain === true,
     ignored,
     edgeUnattested: unattested ?? "signin",
@@ -319,6 +330,43 @@ function clientIdOf(
   return v.trim();
 }
 
+// ── The approval key (0.4.15) ─────────────────────────────────────────────
+
+/**
+ * Why a cookie alone can't approve an agent's change: browsers send a
+ * localhost cookie to every localhost port (cookies ignore ports), so a
+ * dev server an agent runs on another port receives Den's session cookie,
+ * and GET /api/session gives any cookie holder the session's CSRF token.
+ * The approval key is a second secret only the signed-in page holds: it
+ * comes in the sign-in's own answer (a 303's URL fragment, which never
+ * reaches a server, or the sign-in poll's JSON), the page keeps it in its
+ * localStorage (per origin, port included), and sends it as
+ * X-Den-Approve-Key.
+ */
+export const APPROVE_KEY_HEADER = "x-den-approve-key";
+/** The fragment parameter a sign-in's 303 carries it in. */
+export const APPROVE_KEY_FRAGMENT = "ak";
+
+export function approveKeyHash(key: string): string {
+  return createHash("sha256").update(`den-approve-v1:${key}`).digest("hex");
+}
+
+/** Whether `given` is the key whose hash the session keeps (constant time). */
+export function approveKeyMatches(
+  storedHash: string | undefined,
+  given: string | undefined | null,
+): boolean {
+  if (!storedHash || !given || !/^[A-Za-z0-9_-]{43}$/.test(given)) return false;
+  const a = Buffer.from(approveKeyHash(given), "hex");
+  const b = Buffer.from(storedHash, "hex");
+  return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}
+
+/** `next` with the approval key in its fragment (a sign-in's 303). */
+export function withApproveKey(next: string, key: string): string {
+  return `${next.split("#")[0]}#${APPROVE_KEY_FRAGMENT}=${key}`;
+}
+
 // ── The session store ──────────────────────────────────────────────────────
 
 export interface SessionRecord {
@@ -329,14 +377,21 @@ export interface SessionRecord {
   csrf: string;
   /** The Host it was issued on. */
   host: string;
-  /** SEC-2a: how it signed in: a GitHub sign-in, or a one-time link (pairing). Unset: a link (before 0.4.5). */
-  via?: "github" | "link" | "code";
+  /** SEC-2a: how it signed in: a GitHub sign-in, a one-time link, a code (pairing), or the install's setup link (claim, 0.4.15). Unset: a link (before 0.4.5). */
+  via?: "github" | "link" | "code" | "claim";
   /** SEC-2a: the client's address when Den could attest it. */
   client?: string;
   /** SEC-2a: a GitHub sign-in's login (the chip's "@login"). */
   login?: string;
   /** SEC-2a: not yet greeted ("This device is signed in…", once). */
   welcome?: true;
+  /**
+   * 0.4.15: sha256 of this session's approval key (approvalKeyMatches).
+   * The key itself is handed over once, at the end of the sign-in, and
+   * never by GET /api/session. Unset: a session from before 0.4.15, which
+   * must sign in again to approve.
+   */
+  approveKeyHash?: string;
 }
 
 interface StoreFile {
@@ -464,14 +519,17 @@ export class WebSessionStore {
   create(meta: {
     userAgent?: string;
     host?: string;
-    via?: "github" | "link" | "code";
+    via?: "github" | "link" | "code" | "claim";
     client?: string;
     login?: string;
   }): {
     id: string;
     session: SessionView;
+    /** The approval key, for the sign-in's answer only (never stored). */
+    approveKey: string;
   } {
     const id = randomBytes(32).toString("base64url");
+    const approveKey = randomBytes(32).toString("base64url");
     const key = this.keyOf(id);
     if (!key) throw new Error("web.secret is missing: no session can be made");
     const now = this.now();
@@ -487,12 +545,13 @@ export class WebSessionStore {
       ...(meta.client ? { client: String(meta.client).slice(0, 64) } : {}),
       ...(meta.login ? { login: String(meta.login).slice(0, 64) } : {}),
       welcome: true,
+      approveKeyHash: approveKeyHash(approveKey),
     };
     const data = structuredClone(this.load());
     this.prune(data, now);
     data.sessions[key] = rec;
     this.save(data);
-    return { id, session: { key, ...rec } };
+    return { id, session: { key, ...rec }, approveKey };
   }
 
   /**

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

@@ -116,6 +116,7 @@ import {
   restoreRecord,
   writeRecord,
   checkDisplayName,
+  nameSlug,
   writeRuntimeFiles,
   type AgentRecord,
   type Override,
@@ -138,6 +139,7 @@ import type {
   RuntimePermissions,
 } from "../../shared/agents/runtime.js";
 import {
+  inScope,
   OPEN_ELSEWHERE_MESSAGE,
   openElsewhere,
   type RuntimeConversation,
@@ -195,7 +197,7 @@ export interface AgentsDeps extends SessionsDeps {
    * AG-17.1: the folders a workspace's conversations may have run in: its
    * own folder, and each repo's path, a repo added by path outside it too.
    */
-  workspaceFolders?: (ws: string) => string[];
+  workspaceFolders?: (ws: string) => { under: string[]; exact?: string[] };
   /** The MCP server binary and its env; Den adds the scoped args. */
   mcpServer?: () => { command: string[] | string; env: Record<string, string> };
   /**
@@ -232,7 +234,7 @@ export interface AgentsResolved extends Resolved {
   agentsConfig: () => ResolvedAgentsConfig;
   distRoot: () => string;
   workspaceDir: (ws: string) => string;
-  workspaceFolders: (ws: string) => string[];
+  workspaceFolders: (ws: string) => { under: string[]; exact?: string[] };
   mcpServer: () => { command: string[] | string; env: Record<string, string> };
   exitWatchMs: number;
   stopWaitMs: number;
@@ -292,7 +294,8 @@ const refused = (message: string, hints: string[] = [], status = 409) =>
   new AgentError(message, { status, hints });
 
 let workspaceDirFn: ((ws: string) => string) | null = null;
-let repoPathsFn: ((ws: string) => string[]) | null = null;
+let foldersFn: ((ws: string) => { under: string[]; exact?: string[] }) | null =
+  null;
 /** The workspaces config, for start and resume (loaded on first use). */
 export async function loadAgentWorkspaces(d: AgentsDeps): Promise<void> {
   await loadWorkspaces(d);
@@ -305,8 +308,11 @@ export async function loadAgentWorkspaces(d: AgentsDeps): Promise<void> {
     return ws.resolveWorkspaceDir(name, cfg, getReposRoot());
   };
   // A by-path repo's own folder (repo add <path>), wherever it is.
-  repoPathsFn = (name) =>
-    ws.repoFolders(ws.readWorkspacesFile().workspaces[name]);
+  foldersFn = (name) => {
+    const cfg = ws.readWorkspacesFile().workspaces[name];
+    if (!cfg) throw usage(`workspace "${name}" does not exist`, 404);
+    return ws.conversationFolders(name, cfg, getReposRoot());
+  };
 }
 
 /** The distribution's bin shim (as `mcp connect` registers), else Den's CLI. */
@@ -340,13 +346,10 @@ export function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
     workspaceFolders:
       d.workspaceFolders ??
       ((ws) => {
-        const dir = d.workspaceDir
-          ? d.workspaceDir(ws)
-          : (() => {
-              if (!workspaceDirFn) throw new Error("workspaces not loaded");
-              return workspaceDirFn(ws);
-            })();
-        return [dir, ...(repoPathsFn?.(ws) ?? [])];
+        // A caller that gives its own folder (a test) gives just it.
+        if (d.workspaceDir) return { under: [d.workspaceDir(ws)] };
+        if (!foldersFn) throw new Error("workspaces not loaded");
+        return foldersFn(ws);
       }),
     mcpServer: d.mcpServer ?? (() => defaultMcpServer(base.cli)),
     exitWatchMs: d.exitWatchMs ?? EXIT_WATCH_MS,
@@ -452,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.
@@ -550,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 } : {}),
@@ -1048,6 +1059,48 @@ function sessionOf(
  * else the first of `<base>-2`, `<base>-3`… no agent has. A stopped agent's
  * id is never reused by a new start: only its Resume or Start fresh.
  */
+/**
+ * AG-10.10b: the id a Name gives: its slug while no agent has it; a
+ * running agent in the workspace with that id or that title is refused
+ * (open it instead); a stopped one, or another workspace's, makes it the
+ * next free `<slug>-2`… (Resume continues the stopped one). Null when the
+ * Name has no id characters: the persona's default then.
+ */
+async function namedId(
+  d: AgentsResolved,
+  name: string,
+  ws: string,
+): Promise<string | null> {
+  const slug = nameSlug(name);
+  const sessions = await withClient(d, (c) => c.list());
+  const live = (rec: AgentRecord) => {
+    const s = sessionOf(sessions, rec);
+    return s && !s.exited ? s : undefined;
+  };
+  // No two live agents in one workspace share a title, or this id.
+  for (const rec of listRecords(d.stateDir())) {
+    if (rec.workspace !== ws) continue;
+    const same =
+      rec.id === slug ||
+      (rec.displayName ?? "").toLowerCase() === name.toLowerCase();
+    const s = same ? live(rec) : undefined;
+    if (s)
+      throw new AgentError(`agent ${rec.id} is running (${s.name})`, {
+        status: 409,
+        hints: [`Attach: ${d.cli} sessions attach ${s.name}`],
+        running: { id: rec.id, sessionId: s.ref.id },
+      });
+  }
+  if (!slug) return null;
+  if (!readRecord(d.stateDir(), slug)) return slug;
+  const stem = slug.slice(0, 58);
+  for (let n = 2; n < 1000; n++) {
+    const id = `${stem}-${n}`;
+    if (!readRecord(d.stateDir(), id)) return id;
+  }
+  throw refused(`no free agent id for ${slug}: give one with --id`);
+}
+
 export function defaultId(
   stateDir: string,
   persona: string,
@@ -1487,8 +1540,6 @@ export async function startAgent(
     throw usage(
       `${where}: no persona "${req.persona}" (personas: ${[...all.keys()].sort().join(", ")})`,
     );
-  const id = req.id ?? defaultId(d.stateDir(), persona.id, ws);
-  checkId(where, id);
   let given: string | null = null;
   if (req.name !== undefined)
     try {
@@ -1496,6 +1547,11 @@ export async function startAgent(
     } catch (e) {
       throw usage(`${where}: ${(e as Error).message}`);
     }
+  const id =
+    req.id ??
+    (given ? await namedId(d, given, ws) : null) ??
+    defaultId(d.stateDir(), persona.id, ws);
+  checkId(where, id);
   syncCatalog(d);
   const rt = runtimeFor(req.runtime ?? persona.runtime ?? DEFAULT_RUNTIME_ID);
   const det = await availableOrRefuse(d, rt, ws);
@@ -1627,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. */
@@ -1678,14 +1745,10 @@ export function listConversations(
     throw usage(`${where}: workspace "${ws}" does not exist`, 404);
   syncCatalog(d);
   if (runtime !== undefined) runtimeFor(runtime);
-  // Its folder and every repo's (one under another is scanned once).
-  const folders = [
-    ...new Set(d.workspaceFolders(ws).map((f) => path.resolve(f))),
-  ];
-  const scan = folders.filter(
-    (f) => !folders.some((o) => o !== f && f.startsWith(o + path.sep)),
-  );
+  // 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>();
@@ -1693,15 +1756,19 @@ export function listConversations(
     if (runtime !== undefined && id !== runtime) continue;
     const rt = getRuntime(id);
     if (!rt?.listSessions) continue;
-    for (const c of scan.flatMap((f) => rt.listSessions!(f, d.env))) {
+    for (const c of rt.listSessions(scope, d.env)) {
       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 } : {}),
       });
     }
   }
@@ -1709,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. */
@@ -1716,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. */
@@ -1755,6 +1859,16 @@ export async function importAgent(
       422,
     );
   const c = conversations.find((x) => x.id === req.session);
+  // Another workspace's (or no repo's): say whose, never bring it in.
+  const elsewhere = c
+    ? null
+    : (getRuntime(runtime)?.conversationCwd?.(req.session, d.env) ?? null);
+  if (!c && elsewhere && !inScope(elsewhere, d.workspaceFolders(req.workspace)))
+    throw refused(
+      `This conversation belongs to ${elsewhere}, not to workspace ${req.workspace}`,
+      [`List this workspace's: ${d.cli} agents import -w ${req.workspace}`],
+      409,
+    );
   if (!c)
     throw refused(
       `${where}: no ${rt.label} conversation "${req.session}" in workspace ${req.workspace}'s folder`,
@@ -1778,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 } },
   );
 }
@@ -2060,6 +2188,227 @@ 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;
+}
+
+/** 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 ─────────────────────────────────────
 
 /**