@desplega.ai/agent-swarm 1.131.1 → 1.133.1

package/src/tests/profile-sync.test.ts

@@ -1,11 +1,14 @@
 import { describe, expect, spyOn, test } from "bun:test";
 import {
   buildIdentityPayload,
+  buildIndependentIdentityPayloads,
   CLAUDE_MD_PATH,
   collectProfilePayloads,
   contentSha256,
   extractSetupScriptContent,
   type FileReader,
+  findProfileDivergences,
+  HEARTBEAT_MD_PATH,
   IDENTITY_BASELINES_PATH,
   IDENTITY_MD_PATH,
   type IdentityBaselines,
@@ -17,7 +20,9 @@ import {
   TOOLS_MD_PATH,
   WORKSPACE_CLAUDE_MD_PATH,
 } from "../commands/profile-sync";
+import { profileSyncAuditExitCode, runProfileSyncAudit } from "../commands/profile-sync-audit";
 import { MAX_PROFILE_FILE_LENGTH } from "../utils/constants";
+import { IDENTITY_FIELD_BUDGETS } from "../utils/identity-field-budget";
 
 const MARKER_START = "# === Agent-managed setup (from DB) ===";
 const MARKER_END = "# === End agent-managed setup ===";
@@ -25,6 +30,182 @@ const MARKER_END = "# === End agent-managed setup ===";
 // A SOUL/IDENTITY body long enough to clear the 500-char min-length guard.
 const LONG = "x".repeat(600);
 
+describe("profile divergence audit", () => {
+  test("compares all four budgeted fields plus ungated heartbeatMd", () => {
+    const divergences = findProfileDivergences(
+      {
+        soulMd: "disk soul",
+        identityMd: "disk identity",
+        claudeMd: "disk claude",
+        toolsMd: "disk tools",
+        heartbeatMd: "disk heartbeat",
+      },
+      {
+        soulMd: "db soul",
+        identityMd: "db identity",
+        claudeMd: "db claude",
+        toolsMd: "db tools",
+        heartbeatMd: "db heartbeat",
+      },
+    );
+
+    expect(divergences.map((entry) => entry.field)).toEqual([
+      "soulMd",
+      "identityMd",
+      "claudeMd",
+      "toolsMd",
+      "heartbeatMd",
+    ]);
+    expect(divergences[0]?.budget).toBe(IDENTITY_FIELD_BUDGETS.soulMd);
+    expect(divergences[2]?.budget).toBe(IDENTITY_FIELD_BUDGETS.claudeMd);
+    expect(divergences[4]?.budget).toBeNull();
+    expect(divergences[4]?.diskSize).toBe("disk heartbeat".length);
+    expect(divergences[4]?.dbSize).toBe("db heartbeat".length);
+  });
+
+  test("fetches the DB profile and reads the canonical local paths", async () => {
+    const local = {
+      [SOUL_MD_PATH]: "same soul",
+      [IDENTITY_MD_PATH]: "disk identity",
+      [WORKSPACE_CLAUDE_MD_PATH]: "same claude",
+      [TOOLS_MD_PATH]: "same tools",
+      [HEARTBEAT_MD_PATH]: "disk heartbeat",
+    };
+    const readFile: FileReader = async (path) => local[path as keyof typeof local];
+    let request: Request | null = null;
+    const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+      request = new Request(input, init);
+      return new Response(
+        JSON.stringify({
+          soulMd: "same soul",
+          identityMd: "db identity",
+          claudeMd: "same claude",
+          toolsMd: "same tools",
+          heartbeatMd: "db heartbeat",
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      );
+    }) as typeof fetch;
+
+    const result = await runProfileSyncAudit(
+      {
+        agentId: "agent-1",
+        apiUrl: "https://api.example.test",
+        apiKey: "secret-key",
+        claudeMdPath: WORKSPACE_CLAUDE_MD_PATH,
+      },
+      { fetchImpl, readFile },
+    );
+
+    expect(request?.url).toBe("https://api.example.test/me");
+    expect(request?.headers.get("X-Agent-ID")).toBe("agent-1");
+    expect(result.divergences.map((entry) => entry.field)).toEqual(["identityMd", "heartbeatMd"]);
+  });
+
+  test("uses the registered effective provider to select the Claude profile path", async () => {
+    const readPaths: string[] = [];
+    const readFile: FileReader = async (path) => {
+      readPaths.push(path);
+      return "same";
+    };
+    const fetchImpl = (async () =>
+      new Response(
+        JSON.stringify({
+          harnessProvider: "codex",
+          soulMd: "same",
+          identityMd: "same",
+          claudeMd: "same",
+          toolsMd: "same",
+          heartbeatMd: "same",
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } },
+      )) as typeof fetch;
+
+    const result = await runProfileSyncAudit(
+      {
+        agentId: "agent-codex",
+        apiUrl: "https://api.example.test",
+        apiKey: "secret-key",
+      },
+      { fetchImpl, readFile },
+    );
+
+    expect(result.divergences).toEqual([]);
+    expect(readPaths).toContain(WORKSPACE_CLAUDE_MD_PATH);
+    expect(readPaths).not.toContain(CLAUDE_MD_PATH);
+  });
+
+  test("refuses to guess the audit path when no effective provider is registered", async () => {
+    const fetchImpl = (async () =>
+      new Response(JSON.stringify({}), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      })) as typeof fetch;
+
+    expect(
+      runProfileSyncAudit(
+        {
+          agentId: "agent-unregistered",
+          apiUrl: "https://api.example.test",
+          apiKey: "secret-key",
+        },
+        { fetchImpl, readFile: async () => undefined },
+      ),
+    ).rejects.toThrow("registered harness provider");
+  });
+
+  test("treats profile fields absent on disk and empty in the DB as equal", async () => {
+    const readFile: FileReader = async () => undefined;
+    const fetchImpl = (async () =>
+      new Response(JSON.stringify({ soulMd: "" }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      })) as typeof fetch;
+
+    const result = await runProfileSyncAudit(
+      {
+        agentId: "agent-unset",
+        apiUrl: "https://api.example.test",
+        apiKey: "secret-key",
+        claudeMdPath: WORKSPACE_CLAUDE_MD_PATH,
+      },
+      { fetchImpl, readFile },
+    );
+
+    expect(result.divergences).toEqual([]);
+    expect(profileSyncAuditExitCode(result.divergences)).toBe(0);
+  });
+
+  test("reports a missing local file when the DB value is non-empty", () => {
+    const divergences = findProfileDivergences(
+      {
+        soulMd: undefined,
+        identityMd: "same identity",
+        claudeMd: "same claude",
+        toolsMd: "same tools",
+        heartbeatMd: "same heartbeat",
+      },
+      {
+        soulMd: "stored soul",
+        identityMd: "same identity",
+        claudeMd: "same claude",
+        toolsMd: "same tools",
+        heartbeatMd: "same heartbeat",
+      },
+    );
+
+    expect(divergences).toHaveLength(1);
+    expect(divergences[0]).toMatchObject({
+      field: "soulMd",
+      diskMissing: true,
+      diskSize: null,
+      diskHash: null,
+      dbSize: "stored soul".length,
+      delta: null,
+    });
+  });
+});
+
 describe("extractSetupScriptContent (marker extraction)", () => {
   test("extracts ONLY the content between the agent-managed markers", () => {
     const raw = [
@@ -97,6 +278,19 @@ describe("buildIdentityPayload (min-length guard)", () => {
     expect(payload.heartbeatMd).toBe("");
   });
 
+  test("forwards oversized gated identity fields so the server ratchet can decide", () => {
+    const oversized = "x".repeat(MAX_PROFILE_FILE_LENGTH + 1);
+    const payload = buildIdentityPayload({
+      soulMd: oversized,
+      identityMd: oversized,
+      toolsMd: oversized,
+    });
+
+    expect(payload.soulMd).toBe(oversized);
+    expect(payload.identityMd).toBe(oversized);
+    expect(payload.toolsMd).toBe(oversized);
+  });
+
   test("logs the agent, field, actual length, and cap when a file is too large", () => {
     const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
     try {
@@ -142,7 +336,13 @@ describe("collectProfilePayloads (field gate)", () => {
       "session_sync",
       files,
     );
-    expect(all.map((p) => p.label).sort()).toEqual(["claude", "identity", "setup"]);
+    expect(all.map((p) => p.label).sort()).toEqual([
+      "claude",
+      "identity.identityMd",
+      "identity.soulMd",
+      "identity.toolsMd",
+      "setup",
+    ]);
   });
 
   test("a missing file yields no payload for that group (no empty POST)", async () => {
@@ -413,11 +613,13 @@ describe("collectProfilePayloads (baseline integration)", () => {
     });
 
     const payloads = await collectProfilePayloads(["identity"], "self_edit", files);
-    expect(payloads).toHaveLength(1);
-    // self_edit should include ALL files regardless of baselines
-    expect(payloads[0]?.body.soulMd).toBe(identityContent);
-    expect(payloads[0]?.body.identityMd).toBe(identityContent);
-    expect(payloads[0]?.body.toolsMd).toBe("tools");
+    expect(payloads).toHaveLength(3);
+    // self_edit should include ALL files regardless of baselines, independently.
+    expect(payloads.map((payload) => payload.body)).toEqual([
+      { soulMd: identityContent, changeSource: "self_edit" },
+      { identityMd: identityContent, changeSource: "self_edit" },
+      { toolsMd: "tools", changeSource: "self_edit" },
+    ]);
   });
 
   test("session_sync skips unchanged CLAUDE.md when baseline matches", async () => {
@@ -482,3 +684,27 @@ describe("collectProfilePayloads (baseline integration)", () => {
     expect(payloads).toEqual([]);
   });
 });
+
+describe("buildIndependentIdentityPayloads", () => {
+  test("splits fields so one rejected write cannot discard valid siblings", () => {
+    expect(
+      buildIndependentIdentityPayloads(
+        { soulMd: "rejected growth", toolsMd: "valid edit", heartbeatMd: "ungated edit" },
+        "session_sync",
+      ),
+    ).toEqual([
+      {
+        label: "identity.soulMd",
+        body: { soulMd: "rejected growth", changeSource: "session_sync" },
+      },
+      {
+        label: "identity.toolsMd",
+        body: { toolsMd: "valid edit", changeSource: "session_sync" },
+      },
+      {
+        label: "identity.heartbeatMd",
+        body: { heartbeatMd: "ungated edit", changeSource: "session_sync" },
+      },
+    ]);
+  });
+});

package/src/tests/prompt-template-session.test.ts

@@ -68,7 +68,7 @@ describe("Session templates — registration", () => {
     await ensureTemplatesRegistered();
   });
 
-  test("all 18 system templates are registered", () => {
+  test("all 19 system templates are registered", () => {
     const systemTemplates = [
       "system.agent.role",
       "system.agent.register",
@@ -89,6 +89,7 @@ describe("Session templates — registration", () => {
       "system.agent.services",
       "system.agent.artifacts",
       "system.agent.share_urls",
+      "system.agent.communication_style",
     ];
 
     for (const eventType of systemTemplates) {
@@ -113,7 +114,7 @@ describe("Session templates — registration", () => {
     }
   });
 
-  test("total of 31 session/system templates registered", () => {
+  test("total of 32 session/system templates registered", () => {
     const all = getAllTemplateDefinitions();
     const sessionSystem = all.filter((d) => d.category === "system" || d.category === "session");
     // 26 = the original 19 + `system.session.worker.pi` + `system.agent.seed_scripts`
@@ -124,7 +125,8 @@ describe("Session templates — registration", () => {
     // 30 = 29 + `system.agent.scheduling` (split out of context_mode so the
     // pi composites keep the scheduling rules without the ctx_* tool block).
     // 31 = 30 + `system.agent.apps`.
-    expect(sessionSystem.length).toBe(31);
+    // 32 = 31 + `system.agent.communication_style`.
+    expect(sessionSystem.length).toBe(32);
   });
 });
 
@@ -332,6 +334,9 @@ describe("Session templates — composite resolution", () => {
     // Contains register section
     expect(result.text).toContain("join-swarm");
 
+    // Lead is hinted to persist learned requester comms preferences
+    expect(result.text).toContain("persist them with its `comms` field");
+
     // Contains lead-specific section (not worker)
     expect(result.text).toContain("CRITICAL: You are a coordinator");
     expect(result.text).toContain("coordinator");
@@ -351,6 +356,9 @@ describe("Session templates — composite resolution", () => {
 
     // Contains system
     expect(result.text).toContain("System packages available");
+
+    // Contains communication style
+    expect(result.text).toContain("### Communication Style");
   });
 
   test("system.session.worker resolves all template references", () => {
@@ -387,6 +395,27 @@ describe("Session templates — composite resolution", () => {
 
     // Contains system
     expect(result.text).toContain("System packages available");
+
+    // Contains communication style
+    expect(result.text).toContain("### Communication Style");
+  });
+
+  test("communication style block resolves in every session composite", () => {
+    const composites = [
+      "system.session.lead",
+      "system.session.worker",
+      "system.session.worker.pi",
+      "system.session.lead.pi",
+      "system.session.worker.remote",
+    ];
+
+    for (const eventType of composites) {
+      const result = resolveTemplate(eventType, { role: "worker", agentId: "agent-001" });
+      expect(result.skipped).toBe(false);
+      expect(result.text).toContain("### Communication Style");
+      expect(result.text).toContain("Mirror the requester");
+      expect(result.text).toContain("Never use em dashes");
+    }
   });
 
   test("composite does NOT include conditional sections (agent_fs, services, artifacts)", () => {

package/src/tests/queue-stall-alarm.test.ts

@@ -0,0 +1,226 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, mock, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, createAgent, createTaskExtended, getDb, initDb, updateTaskVcs } from "../be/db";
+import {
+  _test,
+  checkQueueStall,
+  getQueueStallSnapshot,
+  isQueueStalled,
+  QUEUE_STALL_THRESHOLD_MS,
+} from "../queue-stall-alarm";
+
+const TEST_DB_PATH = "./test-queue-stall-alarm.sqlite";
+const NOW = new Date("2026-08-17T17:00:00.000Z");
+
+beforeAll(() => {
+  closeDb();
+  initDb(TEST_DB_PATH);
+});
+
+beforeEach(() => {
+  _test.resetState();
+  getDb().run("DELETE FROM agent_log");
+  getDb().run("DELETE FROM agent_tasks");
+  getDb().run("DELETE FROM agents");
+});
+
+afterAll(async () => {
+  _test.resetState();
+  closeDb();
+  await unlink(TEST_DB_PATH).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-wal`).catch(() => {});
+  await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
+});
+
+function setCreatedAt(taskId: string, createdAt: string): void {
+  getDb().run("UPDATE agent_tasks SET createdAt = ?, lastUpdatedAt = ? WHERE id = ?", [
+    createdAt,
+    createdAt,
+    taskId,
+  ]);
+  getDb().run(
+    "UPDATE agent_log SET createdAt = ? WHERE taskId = ? AND eventType = 'task_created'",
+    [createdAt, taskId],
+  );
+}
+
+describe("queue stall alarm", () => {
+  test("positive control: alerts when a claimable task is older than 30 minutes", async () => {
+    const worker = createAgent({ name: "worker", isLead: false, status: "idle" });
+    const task = createTaskExtended("Old claimable task", { agentId: worker.id });
+    setCreatedAt(task.id, "2026-08-17T16:29:59.000Z");
+    const notify = mock(async (_message: string) => {});
+
+    const snapshot = await checkQueueStall(NOW, notify);
+
+    expect(isQueueStalled(snapshot)).toBe(true);
+    expect(snapshot.claimableCount).toBe(1);
+    expect(snapshot.oldestTaskId).toBe(task.id);
+    expect(snapshot.oldestAgeMs).toBeGreaterThan(QUEUE_STALL_THRESHOLD_MS);
+    expect(notify).toHaveBeenCalledTimes(1);
+    expect(notify.mock.calls[0]?.[0]).toContain("queue pickup stalled");
+  });
+
+  test("negative control: an empty queue never alerts", async () => {
+    const notify = mock(async (_message: string) => {});
+
+    const snapshot = await checkQueueStall(NOW, notify);
+
+    expect(snapshot.claimableCount).toBe(0);
+    expect(isQueueStalled(snapshot)).toBe(false);
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  test("does not alert for a non-empty but fresh queue", async () => {
+    const task = createTaskExtended("Fresh pool task");
+    setCreatedAt(task.id, "2026-08-17T16:45:00.000Z");
+    const notify = mock(async (_message: string) => {});
+
+    const snapshot = await checkQueueStall(NOW, notify);
+
+    expect(snapshot.claimableCount).toBe(1);
+    expect(isQueueStalled(snapshot)).toBe(false);
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  test("measures queue age from a backlog task becoming claimable", async () => {
+    const task = createTaskExtended("Released backlog task");
+    setCreatedAt(task.id, "2026-08-17T12:00:00.000Z");
+    getDb().run("UPDATE agent_tasks SET status = 'backlog' WHERE id = ?", [task.id]);
+    getDb().run("UPDATE agent_tasks SET status = 'unassigned', lastUpdatedAt = ? WHERE id = ?", [
+      "2026-08-17T16:59:00.000Z",
+      task.id,
+    ]);
+    getDb().run(
+      `INSERT INTO agent_log (id, eventType, taskId, oldValue, newValue, createdAt)
+       VALUES (?, 'task_status_change', ?, 'backlog', 'unassigned', ?)`,
+      [crypto.randomUUID(), task.id, "2026-08-17T16:59:00.000Z"],
+    );
+    const notify = mock(async (_message: string) => {});
+
+    const snapshot = await checkQueueStall(NOW, notify);
+
+    expect(snapshot.oldestAgeMs).toBe(60_000);
+    expect(isQueueStalled(snapshot)).toBe(false);
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  test("measures queue age from the final dependency completing", async () => {
+    const worker = createAgent({ name: "worker", isLead: false, status: "idle" });
+    const prerequisite = createTaskExtended("Prerequisite", { agentId: worker.id });
+    const blocked = createTaskExtended("Newly unblocked", {
+      agentId: worker.id,
+      dependsOn: [prerequisite.id],
+    });
+    setCreatedAt(blocked.id, "2026-08-17T12:00:00.000Z");
+    getDb().run(
+      "UPDATE agent_tasks SET status = 'completed', finishedAt = ?, lastUpdatedAt = ? WHERE id = ?",
+      ["2026-08-17T16:59:00.000Z", "2026-08-17T16:59:00.000Z", prerequisite.id],
+    );
+    const notify = mock(async (_message: string) => {});
+
+    const snapshot = await checkQueueStall(NOW, notify);
+
+    expect(snapshot.oldestTaskId).toBe(blocked.id);
+    expect(snapshot.oldestAgeMs).toBe(60_000);
+    expect(isQueueStalled(snapshot)).toBe(false);
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  test("does not reset queue age when VCS metadata updates a claimable task", () => {
+    const task = createTaskExtended("Old task with new VCS metadata");
+    setCreatedAt(task.id, "2026-08-17T16:00:00.000Z");
+
+    updateTaskVcs(task.id, {
+      vcsProvider: "github",
+      vcsRepo: "desplega-ai/agent-swarm",
+      vcsNumber: 1177,
+      vcsUrl: "https://github.com/desplega-ai/agent-swarm/pull/1177",
+    });
+
+    const snapshot = getQueueStallSnapshot(NOW);
+    expect(snapshot.oldestAgeMs).toBe(60 * 60 * 1000);
+    expect(isQueueStalled(snapshot)).toBe(true);
+  });
+
+  test("does not reset claimable age when VCS metadata updates a completed dependency", () => {
+    const worker = createAgent({ name: "worker", isLead: false, status: "idle" });
+    const prerequisite = createTaskExtended("Completed prerequisite", { agentId: worker.id });
+    const blocked = createTaskExtended("Waiting after prerequisite", {
+      agentId: worker.id,
+      dependsOn: [prerequisite.id],
+    });
+    setCreatedAt(blocked.id, "2026-08-17T12:00:00.000Z");
+    getDb().run(
+      "UPDATE agent_tasks SET status = 'completed', finishedAt = ?, lastUpdatedAt = ? WHERE id = ?",
+      ["2026-08-17T16:00:00.000Z", "2026-08-17T16:00:00.000Z", prerequisite.id],
+    );
+
+    updateTaskVcs(prerequisite.id, {
+      vcsProvider: "github",
+      vcsRepo: "desplega-ai/agent-swarm",
+      vcsNumber: 1177,
+      vcsUrl: "https://github.com/desplega-ai/agent-swarm/pull/1177",
+    });
+
+    const snapshot = getQueueStallSnapshot(NOW);
+    expect(snapshot.oldestTaskId).toBe(blocked.id);
+    expect(snapshot.oldestAgeMs).toBe(60 * 60 * 1000);
+    expect(isQueueStalled(snapshot)).toBe(true);
+  });
+
+  test("excludes pending tasks whose dependencies are not complete", () => {
+    const worker = createAgent({ name: "worker", isLead: false, status: "idle" });
+    const prerequisite = createTaskExtended("Prerequisite", { agentId: worker.id });
+    const blocked = createTaskExtended("Blocked", {
+      agentId: worker.id,
+      dependsOn: [prerequisite.id],
+    });
+    setCreatedAt(blocked.id, "2026-08-17T12:00:00.000Z");
+
+    const snapshot = getQueueStallSnapshot(NOW);
+
+    expect(snapshot.claimableCount).toBe(1);
+    expect(snapshot.oldestTaskId).toBe(prerequisite.id);
+  });
+
+  test("reports direct and pool pickup transitions as diagnostic context", () => {
+    const worker = createAgent({ name: "worker", isLead: false, status: "idle" });
+    const task = createTaskExtended("Queued", { agentId: worker.id });
+    getDb().run(
+      `INSERT INTO agent_log (id, eventType, taskId, agentId, oldValue, newValue, createdAt)
+       VALUES (?, 'task_status_change', ?, ?, 'pending', 'in_progress', ?)`,
+      [crypto.randomUUID(), task.id, worker.id, "2026-08-17T16:50:00.000Z"],
+    );
+    getDb().run(
+      `INSERT INTO agent_log (id, eventType, taskId, agentId, oldValue, newValue, createdAt)
+       VALUES (?, 'task_claimed', ?, ?, 'unassigned', 'in_progress', ?)`,
+      [crypto.randomUUID(), task.id, worker.id, "2026-08-17T16:55:00.000Z"],
+    );
+
+    expect(getQueueStallSnapshot(NOW).recentPickupCount).toBe(2);
+  });
+
+  test("scrubs secrets from notification failures before logging", () => {
+    const token = "ghp_1234567890abcdefABCDEF1234567890ABCD";
+
+    const output = _test.formatCheckFailure(new Error(`Slack rejected token ${token}`));
+
+    expect(output).not.toContain(token);
+    expect(output).toContain("[REDACTED:github_token]");
+  });
+
+  test("deduplicates an active alarm and sends recovery", async () => {
+    const task = createTaskExtended("Old pool task");
+    setCreatedAt(task.id, "2026-08-17T16:00:00.000Z");
+    const notify = mock(async (_message: string) => {});
+
+    await checkQueueStall(NOW, notify);
+    await checkQueueStall(NOW, notify);
+    getDb().run("UPDATE agent_tasks SET status = 'completed' WHERE id = ?", [task.id]);
+    await checkQueueStall(NOW, notify);
+
+    expect(notify).toHaveBeenCalledTimes(2);
+    expect(notify.mock.calls[1]?.[0]).toContain("queue pickup recovered");
+  });
+});

package/src/tests/requester-comms.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { getUserCommsPrefs } from "../utils/requester-comms";
+
+describe("getUserCommsPrefs", () => {
+  test("returns undefined for missing user or metadata", () => {
+    expect(getUserCommsPrefs(undefined)).toBeUndefined();
+    expect(getUserCommsPrefs({ metadata: undefined })).toBeUndefined();
+    expect(getUserCommsPrefs({ metadata: {} })).toBeUndefined();
+  });
+
+  test("returns undefined when comms is not an object", () => {
+    expect(getUserCommsPrefs({ metadata: { comms: "casual" } })).toBeUndefined();
+    expect(getUserCommsPrefs({ metadata: { comms: ["casual"] } })).toBeUndefined();
+    expect(getUserCommsPrefs({ metadata: { comms: null } })).toBeUndefined();
+  });
+
+  test("picks trimmed string fields and drops the rest", () => {
+    expect(
+      getUserCommsPrefs({
+        metadata: {
+          comms: { tone: "  casual  ", language: "uk", verbosity: 3, extra: "ignored" },
+        },
+      }),
+    ).toEqual({ tone: "casual", language: "uk", verbosity: undefined });
+  });
+
+  test("returns undefined when all comms fields are empty or non-string", () => {
+    expect(
+      getUserCommsPrefs({ metadata: { comms: { tone: "   ", language: 7 } } }),
+    ).toBeUndefined();
+  });
+});

package/src/tests/runner-requester-profile.test.ts

@@ -22,4 +22,42 @@ describe("runner requester profile prompt", () => {
     expect(prompt).toContain("Lead with the answer; keep updates terse.");
     expect(prompt).toContain("where it doesn't conflict with correctness or your operating rules");
   });
+
+  test("renders structured comms preferences alongside role and notes", async () => {
+    const prompt = await buildRequesterProfilePrompt({
+      name: "Taras",
+      role: "CEO",
+      notes: "Keep updates terse.",
+      comms: { tone: "casual", language: "Ukrainian", verbosity: "terse" },
+    });
+
+    expect(prompt).toContain(
+      "Their communication preferences: tone: casual, language: Ukrainian, verbosity: terse.",
+    );
+    expect(prompt).toContain("Their stated notes for how you should respond and act:");
+  });
+
+  test("fires when only comms preferences are set", async () => {
+    const prompt = await buildRequesterProfilePrompt({
+      name: "Taras",
+      comms: { language: "Ukrainian" },
+    });
+
+    expect(prompt).toContain("## Requester Profile");
+    expect(prompt).toContain("This task was requested by Taras.");
+    expect(prompt).toContain("Their communication preferences: language: Ukrainian.");
+    expect(prompt).not.toContain("Their stated notes");
+  });
+
+  test("hints that learned preferences should be persisted via manage-user", async () => {
+    const prompt = await buildRequesterProfilePrompt({ name: "Taras", role: "CEO" });
+
+    expect(prompt).toContain(
+      "the lead updates `comms` (tone, language, verbosity) via `manage-user`",
+    );
+  });
+
+  test("ignores empty comms object", async () => {
+    await expect(buildRequesterProfilePrompt({ name: "Taras", comms: {} })).resolves.toBe("");
+  });
 });