@botcord/daemon 0.2.5 → 0.2.6

package/src/__tests__/policy-updated-handler.test.ts

@@ -0,0 +1,144 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockState = {
+  cfg: {
+    defaultRoute: { adapter: "claude-code", cwd: "/tmp" },
+    routes: [],
+    streamBlocks: true,
+  } as Record<string, unknown>,
+  saved: [] as Array<Record<string, unknown>>,
+};
+
+vi.mock("../config.js", async () => {
+  const actual = await vi.importActual<typeof import("../config.js")>("../config.js");
+  return {
+    ...actual,
+    loadConfig: () => JSON.parse(JSON.stringify(mockState.cfg)) as Record<string, unknown>,
+    saveConfig: (next: Record<string, unknown>) => {
+      mockState.cfg = JSON.parse(JSON.stringify(next)) as Record<string, unknown>;
+      mockState.saved.push(JSON.parse(JSON.stringify(next)) as Record<string, unknown>);
+    },
+  };
+});
+
+const { createProvisioner } = await import("../provision.js");
+const { CONTROL_FRAME_TYPES } = await import("@botcord/protocol-core");
+import type { GatewayRoute, GatewayRuntimeSnapshot } from "../gateway/index.js";
+import type { PolicyResolverLike } from "../gateway/policy-resolver.js";
+
+beforeEach(() => {
+  mockState.cfg = {
+    defaultRoute: { adapter: "claude-code", cwd: "/tmp" },
+    routes: [],
+    streamBlocks: true,
+  };
+  mockState.saved = [];
+});
+
+function makeFakeGateway(): unknown {
+  const snap: GatewayRuntimeSnapshot = { channels: {}, turns: {} };
+  return {
+    addChannel: vi.fn(async () => {}),
+    removeChannel: vi.fn(async () => {}),
+    upsertManagedRoute: vi.fn(),
+    removeManagedRoute: vi.fn(),
+    replaceManagedRoutes: vi.fn(),
+    listManagedRoutes: () => [] as GatewayRoute[],
+    snapshot: () => snap,
+  };
+}
+
+function makeFakeResolver(): PolicyResolverLike & {
+  invalidate: ReturnType<typeof vi.fn>;
+  put: ReturnType<typeof vi.fn>;
+  resolve: ReturnType<typeof vi.fn>;
+} {
+  return {
+    resolve: vi.fn(async () => ({ mode: "always", keywords: [] })),
+    invalidate: vi.fn(),
+    put: vi.fn(),
+  };
+}
+
+describe("policy_updated control-frame handler", () => {
+  it("invalidates the resolver cache for the agent when payload has no policy", async () => {
+    const gw = makeFakeGateway();
+    const resolver = makeFakeResolver();
+    const provisioner = createProvisioner({
+      gateway: gw as Parameters<typeof createProvisioner>[0]["gateway"],
+      policyResolver: resolver,
+    });
+    const ack = await provisioner({
+      id: "f1",
+      type: CONTROL_FRAME_TYPES.POLICY_UPDATED,
+      params: { agent_id: "ag_a" },
+    });
+    expect(ack.ok).toBe(true);
+    expect(resolver.invalidate).toHaveBeenCalledWith("ag_a", undefined);
+    expect(resolver.put).not.toHaveBeenCalled();
+  });
+
+  it("invalidates only the per-room slot when room_id is present", async () => {
+    const resolver = makeFakeResolver();
+    const provisioner = createProvisioner({
+      gateway: makeFakeGateway() as Parameters<typeof createProvisioner>[0]["gateway"],
+      policyResolver: resolver,
+    });
+    await provisioner({
+      id: "f2",
+      type: CONTROL_FRAME_TYPES.POLICY_UPDATED,
+      params: { agent_id: "ag_a", room_id: "rm_1" },
+    });
+    expect(resolver.invalidate).toHaveBeenCalledWith("ag_a", "rm_1");
+  });
+
+  it("calls put() with the embedded policy when payload carries one", async () => {
+    const resolver = makeFakeResolver();
+    const provisioner = createProvisioner({
+      gateway: makeFakeGateway() as Parameters<typeof createProvisioner>[0]["gateway"],
+      policyResolver: resolver,
+    });
+    const ack = await provisioner({
+      id: "f3",
+      type: CONTROL_FRAME_TYPES.POLICY_UPDATED,
+      params: {
+        agent_id: "ag_a",
+        policy: { mode: "keyword", keywords: ["foo", "bar"], muted_until: 123 },
+      },
+    });
+    expect(ack.ok).toBe(true);
+    expect(resolver.put).toHaveBeenCalledWith("ag_a", null, {
+      mode: "keyword",
+      keywords: ["foo", "bar"],
+      muted_until: 123,
+    });
+    expect(resolver.invalidate).not.toHaveBeenCalled();
+  });
+
+  it("rejects payloads missing agent_id with bad_params", async () => {
+    const resolver = makeFakeResolver();
+    const provisioner = createProvisioner({
+      gateway: makeFakeGateway() as Parameters<typeof createProvisioner>[0]["gateway"],
+      policyResolver: resolver,
+    });
+    const ack = await provisioner({
+      id: "f4",
+      type: CONTROL_FRAME_TYPES.POLICY_UPDATED,
+      params: {},
+    });
+    expect(ack.ok).toBe(false);
+    expect(ack.error?.code).toBe("bad_params");
+  });
+
+  it("succeeds quietly when no resolver is wired", async () => {
+    const provisioner = createProvisioner({
+      gateway: makeFakeGateway() as Parameters<typeof createProvisioner>[0]["gateway"],
+    });
+    const ack = await provisioner({
+      id: "f5",
+      type: CONTROL_FRAME_TYPES.POLICY_UPDATED,
+      params: { agent_id: "ag_a" },
+    });
+    expect(ack.ok).toBe(true);
+  });
+});

package/src/__tests__/provision.test.ts

@@ -298,6 +298,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",
@@ -920,3 +972,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;
+  }
+}