@botcord/daemon 0.2.5 → 0.2.8

package/src/__tests__/provision.test.ts

@@ -26,6 +26,7 @@ vi.mock("../config.js", async () => {
 
 const {
   addAgentToConfig,
+  adoptDiscoveredOpenclawAgents,
   removeAgentFromConfig,
   reloadConfig,
   setRoute,
@@ -298,6 +299,58 @@ describe("set_route handler", () => {
     expect(saved.routes[0].extraArgs).toEqual(["--debug"]);
   });
 
+  it("inherits defaultRoute.extraArgs when caller omits them (mirrors adapter/cwd fallback)", () => {
+    mockState.cfg = {
+      defaultRoute: {
+        adapter: "claude-code",
+        cwd: process.env.HOME ?? "/tmp",
+        extraArgs: ["--permission-mode", "bypassPermissions"],
+      },
+      routes: [],
+      streamBlocks: true,
+    };
+    setRoute({ agentId: "ag_new", pattern: "rm_oc_" });
+    const saved = mockState.saved[mockState.saved.length - 1] as unknown as DaemonConfig;
+    expect(saved.routes[0].extraArgs).toEqual([
+      "--permission-mode",
+      "bypassPermissions",
+    ]);
+    // Mutating the saved route must not bleed back into defaultRoute.
+    saved.routes[0].extraArgs!.push("--mutated");
+    expect(mockState.cfg.defaultRoute).toEqual({
+      adapter: "claude-code",
+      cwd: process.env.HOME ?? "/tmp",
+      extraArgs: ["--permission-mode", "bypassPermissions"],
+    });
+  });
+
+  it("explicit extraArgs override defaultRoute.extraArgs", () => {
+    mockState.cfg = {
+      defaultRoute: {
+        adapter: "claude-code",
+        cwd: process.env.HOME ?? "/tmp",
+        extraArgs: ["--permission-mode", "bypassPermissions"],
+      },
+      routes: [],
+      streamBlocks: true,
+    };
+    setRoute({
+      agentId: "ag_new",
+      route: { adapter: "claude-code", cwd: process.env.HOME ?? "/tmp", extraArgs: ["--debug"] },
+    });
+    const saved = mockState.saved[mockState.saved.length - 1] as unknown as DaemonConfig;
+    expect(saved.routes[0].extraArgs).toEqual(["--debug"]);
+  });
+
+  it("omits extraArgs when neither route nor defaultRoute provide them", () => {
+    setRoute({
+      agentId: "ag_new",
+      route: { adapter: "claude-code", cwd: process.env.HOME ?? "/tmp" },
+    });
+    const saved = mockState.saved[mockState.saved.length - 1] as unknown as DaemonConfig;
+    expect(saved.routes[0]).not.toHaveProperty("extraArgs");
+  });
+
   it("forces match.accountId to the agentId even when callers omit it", () => {
     setRoute({
       agentId: "ag_x",
@@ -727,6 +780,110 @@ describe("provision_agent seeds workspace + hot-adds managed route", () => {
   });
 });
 
+describe("adoptDiscoveredOpenclawAgents", () => {
+  it("registers unbound OpenClaw agents and writes the routing binding", async () => {
+    await withSandboxHome(async ({ tmp, fs, path: nodePath }) => {
+      const credDir = nodePath.join(tmp, ".botcord", "credentials");
+      fs.mkdirSync(credDir, { recursive: true });
+      fs.writeFileSync(
+        nodePath.join(credDir, "ag_seed.json"),
+        JSON.stringify({
+          version: 1,
+          hubUrl: "https://hub.example",
+          agentId: "ag_seed",
+          keyId: "k_seed",
+          privateKey: Buffer.alloc(32, 5).toString("base64"),
+          savedAt: new Date().toISOString(),
+        }),
+      );
+      mockState.cfg = {
+        defaultRoute: { adapter: "claude-code", cwd: "/tmp" },
+        routes: [],
+        streamBlocks: true,
+        agents: ["ag_seed"],
+        openclawGateways: [{ name: "local", url: "ws://127.0.0.1:18789" }],
+      };
+
+      const gw = makeFakeGateway(["ag_seed"]);
+      const register = vi.fn(async () => ({
+        agentId: "ag_adopted",
+        keyId: "k_adopted",
+        privateKey: Buffer.alloc(32, 31).toString("base64"),
+        publicKey: Buffer.alloc(32, 32).toString("base64"),
+        hubUrl: "https://hub.example",
+        token: "tok",
+        expiresAt: Date.now() + 60_000,
+      }));
+
+      const res = await adoptDiscoveredOpenclawAgents({
+        gateway: gw as unknown as Parameters<typeof adoptDiscoveredOpenclawAgents>[0]["gateway"],
+        register: register as unknown as Parameters<typeof adoptDiscoveredOpenclawAgents>[0]["register"],
+        cfg: mockState.cfg as unknown as DaemonConfig,
+        probe: async () => ({ ok: true, agents: [{ id: "main", name: "Main Agent" }] }),
+      });
+
+      expect(res.adopted).toEqual(["ag_adopted"]);
+      expect(register).toHaveBeenCalledWith("https://hub.example", "Main Agent", undefined);
+      const saved = JSON.parse(
+        fs.readFileSync(nodePath.join(credDir, "ag_adopted.json"), "utf8"),
+      ) as Record<string, unknown>;
+      expect(saved.runtime).toBe("openclaw-acp");
+      expect(saved.openclawGateway).toBe("local");
+      expect(saved.openclawAgent).toBe("main");
+      expect((mockState.cfg.agents as string[])).toContain("ag_adopted");
+      expect(gw.addChannel).toHaveBeenCalledWith(
+        expect.objectContaining({ id: "ag_adopted", type: "botcord" }),
+      );
+      const route = gw.listManagedRoutes().find((r) => r.match?.accountId === "ag_adopted");
+      expect(route?.runtime).toBe("openclaw-acp");
+      expect(route?.gateway?.name).toBe("local");
+      expect(route?.gateway?.openclawAgent).toBe("main");
+    });
+  });
+
+  it("skips an OpenClaw agent that is already bound in credentials", async () => {
+    await withSandboxHome(async ({ tmp, fs, path: nodePath }) => {
+      const credDir = nodePath.join(tmp, ".botcord", "credentials");
+      fs.mkdirSync(credDir, { recursive: true });
+      fs.writeFileSync(
+        nodePath.join(credDir, "ag_existing.json"),
+        JSON.stringify({
+          version: 1,
+          hubUrl: "https://hub.example",
+          agentId: "ag_existing",
+          keyId: "k_existing",
+          privateKey: Buffer.alloc(32, 6).toString("base64"),
+          savedAt: new Date().toISOString(),
+          runtime: "openclaw-acp",
+          openclawGateway: "local",
+          openclawAgent: "main",
+        }),
+      );
+      mockState.cfg = {
+        defaultRoute: { adapter: "claude-code", cwd: "/tmp" },
+        routes: [],
+        streamBlocks: true,
+        agents: ["ag_existing"],
+        openclawGateways: [{ name: "local", url: "ws://127.0.0.1:18789" }],
+      };
+      const register = vi.fn();
+
+      const res = await adoptDiscoveredOpenclawAgents({
+        gateway: makeFakeGateway(["ag_existing"]) as unknown as Parameters<typeof adoptDiscoveredOpenclawAgents>[0]["gateway"],
+        register: register as unknown as Parameters<typeof adoptDiscoveredOpenclawAgents>[0]["register"],
+        cfg: mockState.cfg as unknown as DaemonConfig,
+        probe: async () => ({ ok: true, agents: [{ id: "main" }] }),
+      });
+
+      expect(res.adopted).toEqual([]);
+      expect(res.skipped).toEqual([
+        { gateway: "local", openclawAgent: "main", reason: "already_bound" },
+      ]);
+      expect(register).not.toHaveBeenCalled();
+    });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // revoke_agent — new flag semantics (plan §11.3)
 // ---------------------------------------------------------------------------
@@ -920,3 +1077,111 @@ describe("revoke_agent respects deleteState / deleteWorkspace flags", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// hello + update_agent identity sync (lightweight reconcile path)
+// ---------------------------------------------------------------------------
+
+describe("hello identity snapshot", () => {
+  it("rewrites identity.md for every agent in the snapshot", async () => {
+    await withSandboxHome(async ({ tmp, fs, path: nodePath }) => {
+      const { ensureAgentWorkspace } = await import("../agent-workspace.js");
+      ensureAgentWorkspace("ag_h1", { displayName: "Old1", bio: "Old bio 1" });
+      ensureAgentWorkspace("ag_h2", { displayName: "Old2", bio: "Old bio 2" });
+      void tmp;
+
+      const gw = makeFakeGateway();
+      const provisioner = createProvisioner({
+        gateway: gw as unknown as Parameters<typeof createProvisioner>[0]["gateway"],
+      });
+
+      const ack = await provisioner({
+        id: "req_hello",
+        type: CONTROL_FRAME_TYPES.HELLO,
+        params: {
+          server_time: Date.now(),
+          agents: [
+            { agentId: "ag_h1", displayName: "Fresh1", bio: "Fresh bio 1" },
+            { agentId: "ag_h2", displayName: "Fresh2", bio: null },
+            { agentId: "ag_missing", displayName: "Nope", bio: "Nope" },
+          ],
+        },
+      });
+      expect(ack.ok).toBe(true);
+      const result = ack.result as { updated: number; skipped: number };
+      expect(result.updated).toBe(2);
+      expect(result.skipped).toBe(1);
+
+      const id1 = fs.readFileSync(
+        nodePath.join(tmp, ".botcord", "agents", "ag_h1", "workspace", "identity.md"),
+        "utf8",
+      );
+      expect(id1).toContain("Fresh1");
+      expect(id1).toContain("Fresh bio 1");
+      expect(id1).not.toContain("Old1");
+
+      const id2 = fs.readFileSync(
+        nodePath.join(tmp, ".botcord", "agents", "ag_h2", "workspace", "identity.md"),
+        "utf8",
+      );
+      expect(id2).toContain("Fresh2");
+      // bio cleared → placeholder
+      expect(id2).toContain("_(none provided at provision time");
+    });
+  });
+
+  it("tolerates a hello frame with no agents array", async () => {
+    const gw = makeFakeGateway();
+    const provisioner = createProvisioner({
+      gateway: gw as unknown as Parameters<typeof createProvisioner>[0]["gateway"],
+    });
+    const ack = await provisioner({
+      id: "req_hello_empty",
+      type: CONTROL_FRAME_TYPES.HELLO,
+      params: { server_time: Date.now() },
+    });
+    expect(ack.ok).toBe(true);
+  });
+});
+
+describe("update_agent handler", () => {
+  it("rewrites identity.md for the targeted agent", async () => {
+    await withSandboxHome(async ({ tmp, fs, path: nodePath }) => {
+      const { ensureAgentWorkspace } = await import("../agent-workspace.js");
+      ensureAgentWorkspace("ag_u1", { displayName: "Before", bio: "Before bio" });
+
+      const gw = makeFakeGateway();
+      const provisioner = createProvisioner({
+        gateway: gw as unknown as Parameters<typeof createProvisioner>[0]["gateway"],
+      });
+      const ack = await provisioner({
+        id: "req_update",
+        type: CONTROL_FRAME_TYPES.UPDATE_AGENT,
+        params: { agentId: "ag_u1", displayName: "After", bio: "After bio" },
+      });
+      expect(ack.ok).toBe(true);
+      expect((ack.result as { changed: boolean }).changed).toBe(true);
+
+      const md = fs.readFileSync(
+        nodePath.join(tmp, ".botcord", "agents", "ag_u1", "workspace", "identity.md"),
+        "utf8",
+      );
+      expect(md).toContain("After");
+      expect(md).toContain("After bio");
+    });
+  });
+
+  it("rejects update_agent without agentId", async () => {
+    const gw = makeFakeGateway();
+    const provisioner = createProvisioner({
+      gateway: gw as unknown as Parameters<typeof createProvisioner>[0]["gateway"],
+    });
+    const ack = await provisioner({
+      id: "req_update_bad",
+      type: CONTROL_FRAME_TYPES.UPDATE_AGENT,
+      params: {},
+    });
+    expect(ack.ok).toBe(false);
+    expect(ack.error?.code).toBe("bad_params");
+  });
+});

package/src/__tests__/system-context.test.ts

@@ -25,6 +25,10 @@ const { updateWorkingMemory, clearWorkingMemory } = await import(
 );
 const { ActivityTracker } = await import("../activity-tracker.js");
 const { createDaemonSystemContextBuilder } = await import("../system-context.js");
+const { ensureAgentWorkspace, agentWorkspaceDir } = await import(
+  "../agent-workspace.js"
+);
+const { writeFileSync } = await import("node:fs");
 
 function makeMessage(
   partial: Partial<GatewayInboundMessage> = {},
@@ -82,6 +86,54 @@ describe("createDaemonSystemContextBuilder", () => {
     expect(out).toContain("remember X");
   });
 
+  it("injects the identity block from workspace/identity.md, placed before other blocks", () => {
+    ensureAgentWorkspace("ag_me", {
+      displayName: "Susan's Helper",
+      bio: "A friendly IM agent who tracks contacts.",
+      runtime: "claude-code",
+    });
+    updateWorkingMemory("ag_me", { goal: "ship feature" });
+
+    const builder = createDaemonSystemContextBuilder({ agentId: "ag_me" });
+    const out = builder(makeMessage()) as string;
+    expect(out).toContain("[BotCord Identity]");
+    expect(out).toContain("Susan's Helper");
+    expect(out).toContain("A friendly IM agent who tracks contacts.");
+    // Identity must precede working memory so it frames every other block.
+    expect(out.indexOf("[BotCord Identity]")).toBeLessThan(
+      out.indexOf("[BotCord Working Memory]"),
+    );
+  });
+
+  it("re-reads identity.md every turn so dashboard / agent edits take effect immediately", () => {
+    ensureAgentWorkspace("ag_me", { displayName: "Old Name" });
+    const builder = createDaemonSystemContextBuilder({ agentId: "ag_me" });
+    const first = builder(makeMessage()) as string;
+    expect(first).toContain("Old Name");
+
+    // Simulate an out-of-band edit (dashboard reconcile, user, control frame…).
+    writeFileSync(
+      path.join(agentWorkspaceDir("ag_me"), "identity.md"),
+      "# Identity\n\n- **Display name**: New Name\n",
+    );
+    const second = builder(makeMessage()) as string;
+    expect(second).toContain("New Name");
+    expect(second).not.toContain("Old Name");
+  });
+
+  it("skips the identity block cleanly when identity.md is missing", () => {
+    // No ensureAgentWorkspace — workspace never provisioned.
+    const builder = createDaemonSystemContextBuilder({ agentId: "ag_me" });
+    expect(builder(makeMessage())).toBeUndefined();
+  });
+
+  it("skips the identity block when identity.md is blank", () => {
+    ensureAgentWorkspace("ag_me", { displayName: "X" });
+    writeFileSync(path.join(agentWorkspaceDir("ag_me"), "identity.md"), "");
+    const builder = createDaemonSystemContextBuilder({ agentId: "ag_me" });
+    expect(builder(makeMessage())).toBeUndefined();
+  });
+
   it("emits the 'memory is currently empty' notice when the memory file exists but is blank", () => {
     clearWorkingMemory("ag_me");
     const builder = createDaemonSystemContextBuilder({ agentId: "ag_me" });

package/src/__tests__/url-utils.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { appendNextParam } from "../url-utils.js";
+
+describe("appendNextParam", () => {
+  it("appends next to a URL with no existing query string", () => {
+    const out = appendNextParam(
+      "https://app.botcord.chat/activate",
+      "/settings/daemons",
+    );
+    expect(out).toBe("https://app.botcord.chat/activate?next=%2Fsettings%2Fdaemons");
+  });
+
+  it("preserves existing query params (e.g. ?code=...)", () => {
+    const out = appendNextParam(
+      "https://app.botcord.chat/activate?code=ABCD-EFGH",
+      "/settings/daemons",
+    );
+    const u = new URL(out);
+    expect(u.searchParams.get("code")).toBe("ABCD-EFGH");
+    expect(u.searchParams.get("next")).toBe("/settings/daemons");
+  });
+
+  it("overwrites an existing next param rather than duplicating it", () => {
+    const out = appendNextParam(
+      "https://app.botcord.chat/activate?next=/old",
+      "/settings/daemons",
+    );
+    const u = new URL(out);
+    // searchParams.getAll guards against ?next=/old&next=/new style duplicates
+    expect(u.searchParams.getAll("next")).toEqual(["/settings/daemons"]);
+  });
+
+  it("returns the original string when the URL cannot be parsed", () => {
+    const out = appendNextParam("not a url", "/settings/daemons");
+    expect(out).toBe("not a url");
+  });
+});

package/src/agent-discovery.ts

@@ -38,6 +38,10 @@ export interface DiscoveredAgentCredential {
   runtime?: string;
   /** Working directory cached alongside `runtime`. */
   cwd?: string;
+  /** OpenClaw gateway profile name from credentials (only meaningful for openclaw-acp). */
+  openclawGateway?: string;
+  /** OpenClaw agent profile override from credentials. */
+  openclawAgent?: string;
   /** Key id from the credentials file — surfaced so boot-time workspace
    * seeding (see daemon-agent-workspace-plan.md §9) can render identity.md
    * without re-reading the file. */
@@ -164,6 +168,8 @@ export function discoverAgentCredentials(
     if (creds.displayName) entry.displayName = creds.displayName;
     if (creds.runtime) entry.runtime = creds.runtime;
     if (creds.cwd) entry.cwd = creds.cwd;
+    if (creds.openclawGateway) entry.openclawGateway = creds.openclawGateway;
+    if (creds.openclawAgent) entry.openclawAgent = creds.openclawAgent;
     if (creds.keyId) entry.keyId = creds.keyId;
     if (creds.savedAt) entry.savedAt = creds.savedAt;
     agents.push(entry);
@@ -236,6 +242,8 @@ export function resolveBootAgents(
         if (creds.displayName) entry.displayName = creds.displayName;
         if (creds.runtime) entry.runtime = creds.runtime;
         if (creds.cwd) entry.cwd = creds.cwd;
+        if (creds.openclawGateway) entry.openclawGateway = creds.openclawGateway;
+        if (creds.openclawAgent) entry.openclawAgent = creds.openclawAgent;
         if (creds.keyId) entry.keyId = creds.keyId;
         if (creds.savedAt) entry.savedAt = creds.savedAt;
       } catch (err) {

package/src/agent-workspace.ts

@@ -7,6 +7,14 @@
  *   codex-home/  — per-agent CODEX_HOME used by the codex adapter so codex
  *                  reads a daemon-written AGENTS.md (systemContext carrier)
  *                  and stores its sessions/ without touching ~/.codex.
+ *   hermes-home/      — per-agent HERMES_HOME used by the hermes-acp
+ *                       adapter (carries .env, state.db, skills/) so
+ *                       hermes-acp's per-user state stays isolated.
+ *   hermes-workspace/ — per-agent runtime cwd for hermes-acp; the adapter
+ *                       writes systemContext into AGENTS.md here every turn.
+ *                       Kept separate from `workspace/` so daemon-written
+ *                       systemContext does not clobber the user/agent-
+ *                       editable workspace AGENTS.md.
  */
 import {
   chmodSync,
@@ -14,6 +22,7 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
+  readFileSync,
   readlinkSync,
   symlinkSync,
   unlinkSync,
@@ -58,6 +67,26 @@ export function agentCodexHomeDir(agentId: string): string {
   return path.join(agentHomeDir(agentId), "codex-home");
 }
 
+/**
+ * Per-agent HERMES_HOME. Carries the hermes-acp `.env`, `state.db`, and
+ * `skills/` so each daemon-managed agent has an isolated hermes config
+ * tree and never reads/writes the user's `~/.hermes`.
+ */
+export function agentHermesHomeDir(agentId: string): string {
+  return path.join(agentHomeDir(agentId), "hermes-home");
+}
+
+/**
+ * Per-agent runtime cwd for hermes-acp. Distinct from `workspace/` so the
+ * adapter can rewrite `AGENTS.md` here every turn (carrying the dynamic
+ * systemContext) without clobbering the user/agent-editable workspace
+ * `AGENTS.md`. hermes discovers `AGENTS.md` from cwd upward, so the file
+ * must live alongside the spawn cwd.
+ */
+export function agentHermesWorkspaceDir(agentId: string): string {
+  return path.join(agentHomeDir(agentId), "hermes-workspace");
+}
+
 export interface WorkspaceSeed {
   displayName?: string;
   bio?: string;
@@ -87,10 +116,14 @@ This directory is your persistent workspace. You run with \`cwd\` set here.
 
 ## How to use this
 
-You are **instructed** to skim \`identity.md\`, \`memory.md\`, \`task.md\` before each
-response and to write back what changed after meaningful turns. Nothing in the
-runtime enforces this — the daemon does not auto-load these files into your
-context. Treat AGENTS.md as a convention, not a mechanism.
+- \`identity.md\` is **auto-loaded** by the daemon and injected into every turn's
+  system context as the \`[BotCord Identity]\` block. Edits to this file (yours,
+  the dashboard's via \`applyAgentIdentity\`, or a hello-snapshot reapply) take
+  effect on the next turn — no restart needed.
+- \`memory.md\` and \`task.md\` are **convention, not mechanism**. The daemon does
+  not auto-load them; you are instructed to skim them before responding and to
+  write back what changed after meaningful turns. Keep them tight enough to be
+  worth re-reading.
 `;
 
 const MEMORY_MD = `# Memory
@@ -98,9 +131,9 @@ const MEMORY_MD = `# Memory
 <!--
 Long-lived facts about the user, past decisions, and preferences that should
 survive across conversations. Organize by topic. Keep entries short. Prune
-regularly — AGENTS.md instructs the runtime to consult this file before each
-response, but nothing loads it automatically; keep it short enough to be
-worth re-reading.
+regularly — AGENTS.md instructs you to consult this file before each
+response, but nothing loads it automatically (unlike identity.md); keep it
+short enough to be worth re-reading.
 -->
 `;
 
@@ -215,6 +248,28 @@ export function ensureAgentCodexHome(agentId: string): string {
   return dir;
 }
 
+/**
+ * Idempotently create the per-agent HERMES_HOME and HERMES workspace
+ * directories. Writes a stub `.env` inside HERMES_HOME so hermes-acp's
+ * `_load_env` does not log "No .env found" on every spawn; users can edit
+ * this file to add API keys / model overrides.
+ */
+export function ensureAgentHermesWorkspace(agentId: string): {
+  hermesHome: string;
+  hermesWorkspace: string;
+} {
+  const hermesHome = agentHermesHomeDir(agentId);
+  const hermesWorkspace = agentHermesWorkspaceDir(agentId);
+  mkdirTolerant(hermesHome);
+  mkdirTolerant(hermesWorkspace);
+  writeIfMissing(
+    path.join(hermesHome, ".env"),
+    "# hermes-agent environment overrides for this BotCord agent.\n" +
+      "# Add e.g. HERMES_INFERENCE_PROVIDER=openrouter, OPENROUTER_API_KEY=...\n",
+  );
+  return { hermesHome, hermesWorkspace };
+}
+
 /**
  * Idempotently create the agent's home / workspace / state directories and
  * seed the workspace Markdown files. Existing files are never overwritten —
@@ -233,6 +288,7 @@ export function ensureAgentWorkspace(agentId: string, seed: WorkspaceSeed): void
   mkdirTolerant(notes);
   mkdirTolerant(state);
   ensureAgentCodexHome(agentId);
+  ensureAgentHermesWorkspace(agentId);
 
   const agentsMdPath = path.join(workspace, "AGENTS.md");
   const claudeMdPath = path.join(workspace, "CLAUDE.md");
@@ -243,3 +299,113 @@ export function ensureAgentWorkspace(agentId: string, seed: WorkspaceSeed): void
   writeIfMissing(path.join(workspace, "task.md"), TASK_MD);
   writeIfMissing(path.join(notes, ".gitkeep"), "");
 }
+
+/** Patch fields accepted by {@link applyAgentIdentity}. `bio = null` clears it. */
+export interface AgentIdentityPatch {
+  displayName?: string;
+  bio?: string | null;
+}
+
+/**
+ * Result of applying an identity patch. `changed` is true only when the
+ * file was rewritten on disk; `skipped` reports why (no-op vs. unable).
+ */
+export interface AgentIdentityApplyResult {
+  changed: boolean;
+  skipped?: "missing-file" | "no-change" | "unparseable";
+}
+
+const DISPLAY_NAME_LINE = /^- \*\*Display name\*\*: .*$/m;
+// Match the Bio section's body. Anchor on the next `##` heading when one
+// exists, otherwise consume to end-of-file — keeps the rewrite working when
+// the user has stripped Role/Boundaries sections.
+const BIO_SECTION = /(## Bio\n\n)([\s\S]*?)(\n+##\s|$)/;
+
+/**
+ * Surgically rewrite the `Display name` and `Bio` fields inside an existing
+ * `identity.md`, preserving anything the user has authored elsewhere
+ * (Role / Boundaries / arbitrary new sections). No-op when the file is
+ * missing — provisioning will create it with the correct values, and
+ * subsequent hello snapshots simply reapply the dashboard truth.
+ *
+ * The identity.md template carries `Role` / `Boundaries` headings after
+ * `## Bio`; we anchor the Bio rewrite on "next `##`" so user-added
+ * paragraphs inside Bio are replaced wholesale (the dashboard is the
+ * source of truth) without disturbing siblings.
+ */
+export function applyAgentIdentity(
+  agentId: string,
+  patch: AgentIdentityPatch,
+): AgentIdentityApplyResult {
+  assertSafeAgentId(agentId);
+  const file = path.join(agentWorkspaceDir(agentId), "identity.md");
+  if (!existsSync(file)) {
+    return { changed: false, skipped: "missing-file" };
+  }
+
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return { changed: false, skipped: "missing-file" };
+  }
+
+  const original = text;
+  let touched = false;
+
+  if (typeof patch.displayName === "string") {
+    const value = patch.displayName.length > 0 ? patch.displayName : FIELD_PLACEHOLDER;
+    if (DISPLAY_NAME_LINE.test(text)) {
+      // Use a function replacer so `$1`, `$&` etc. inside the value are
+      // treated literally rather than as backreferences.
+      text = text.replace(DISPLAY_NAME_LINE, () => `- **Display name**: ${value}`);
+      touched = true;
+    } else {
+      // Heavily-edited file without the canonical metadata block — bail
+      // out rather than guess where to splice.
+      return { changed: false, skipped: "unparseable" };
+    }
+  }
+
+  if (patch.bio !== undefined) {
+    const bioText =
+      patch.bio !== null && patch.bio.trim().length > 0
+        ? patch.bio.trim()
+        : BIO_PLACEHOLDER;
+    if (BIO_SECTION.test(text)) {
+      text = text.replace(BIO_SECTION, (_match, head, _body, tail) => `${head}${bioText}${tail}`);
+      touched = true;
+    } else {
+      return { changed: false, skipped: "unparseable" };
+    }
+  }
+
+  if (!touched || text === original) {
+    return { changed: false, skipped: "no-change" };
+  }
+
+  writeFileSync(file, text, { mode: 0o600 });
+  return { changed: true };
+}
+
+/**
+ * Read the agent's `identity.md` verbatim, if it exists. Returns the raw
+ * contents (including the leading `# Identity` heading) so callers can
+ * splice it into the system context. Returns `null` when the workspace
+ * has not been provisioned yet, the file is empty, or the read fails.
+ *
+ * Each call hits disk — same contract as `readWorkingMemory`, so a
+ * dashboard-driven edit (`applyAgentIdentity` from a control frame, or
+ * a hello-snapshot reapply, or the agent's own self-edit) is visible
+ * on the very next turn without restarting the gateway.
+ */
+export function readIdentity(agentId: string): string | null {
+  assertSafeAgentId(agentId);
+  const file = path.join(agentWorkspaceDir(agentId), "identity.md");
+  try {
+    const raw = readFileSync(file, "utf8");
+    return raw.trim().length > 0 ? raw : null;
+  } catch {
+    return null;
+  }
+}