@desplega.ai/agent-swarm 1.145.0 → 1.147.0

package/src/tests/fixtures/file-lock-holder.ts

@@ -0,0 +1,13 @@
+// Holds a `withFileLock` lock from a separate process: prints "locked" once it
+// has it, then keeps it for `holdMs` (or until killed).
+import { withFileLock } from "../../utils/file-lock";
+
+const [lockPath, holdMs] = process.argv.slice(2);
+const result = await withFileLock(lockPath as string, async () => {
+  console.log("locked");
+  await Bun.sleep(Number(holdMs));
+});
+if (!result.acquired) {
+  console.log(`not-acquired:${result.reason}`);
+  process.exit(1);
+}

package/src/tests/fixtures/hold-file-lock.ts

@@ -0,0 +1,25 @@
+import { withFileLock } from "../../utils/file-lock";
+
+/**
+ * Hold `lockPath` from this process (a live holder) until the returned release
+ * function is awaited. Resolves once the lock is actually held.
+ */
+export async function holdFileLock(lockPath: string): Promise<() => Promise<void>> {
+  let release!: () => void;
+  const released = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  let held!: () => void;
+  const acquired = new Promise<void>((resolve) => {
+    held = resolve;
+  });
+  const holding = withFileLock(lockPath, async () => {
+    held();
+    await released;
+  });
+  await acquired;
+  return async () => {
+    release();
+    await holding;
+  };
+}

package/src/tests/heartbeat-expiry.test.ts

@@ -0,0 +1,188 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createServer } from "node:http";
+import {
+  closeDb,
+  createAgent,
+  getAgentById,
+  getDbClient,
+  initDb,
+  updateAgentProfile,
+} from "../be/db";
+import { handleAgentsRest } from "../http/agents";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { HeartbeatExpiryError, validateHeartbeatExpiry } from "../utils/heartbeat-expiry";
+import { listenOnFreePort } from "./test-net";
+
+const section = (...lines: string[]) => `## Tracked Items\n${lines.join("\n")}\n`;
+
+describe("heartbeat expiry validation", () => {
+  test.each(["DELETE 09-30", "delete on 09-30", "DeLeTe ON 09-30"])("accepts %s", (expiry) => {
+    expect(() => validateHeartbeatExpiry("", section(`- New item. ${expiry}`))).not.toThrow();
+  });
+  test("rejects a new undated item and names it", () => {
+    expect(() => validateHeartbeatExpiry("", section("- Check the queue"))).toThrow(
+      "new tracked item requires DELETE <MM-DD> (or DELETE on <MM-DD>): Check the queue",
+    );
+  });
+  test.each([
+    "📌 Permanent rule",
+    "- 📌 Permanent rule",
+    "- [ ] 📌 Permanent rule",
+  ])("exempts pin durables: %s", (line) => {
+    expect(() => validateHeartbeatExpiry("", section(line))).not.toThrow();
+  });
+  test("does not exempt a pin in the middle of an item", () => {
+    expect(() => validateHeartbeatExpiry("", section("- Check 📌 status"))).toThrow(
+      HeartbeatExpiryError,
+    );
+  });
+  test("allows unchanged, shortened, and edited legacy items", () => {
+    const old = section(
+      "- **Queue:** Check the queue every morning and evening",
+      "- Keep this item",
+    );
+    for (const line of [
+      "- **Queue:** Check the queue every morning and evening",
+      "- **Queue:** Check the queue",
+      "- **Queue:** Inspect pending work weekly",
+    ]) {
+      expect(() => validateHeartbeatExpiry(old, section(line, "- Keep this item"))).not.toThrow();
+    }
+    expect(() =>
+      validateHeartbeatExpiry(section("- Check the queue daily"), section("- Check the queue")),
+    ).not.toThrow();
+  });
+  test("allows pure deletion, including the entire section", () => {
+    expect(() => validateHeartbeatExpiry(section("- Old undated item"), section())).not.toThrow();
+    expect(() => validateHeartbeatExpiry(section("- Old undated item"), "")).not.toThrow();
+  });
+  test("uses the last marker and excludes the marker line and later sections", () => {
+    const next =
+      "## Tracked Items\n- Earlier example\n## Tracked Items (current)\n- New. DELETE 09-30\n## Notes\nUndated notes";
+    expect(() => validateHeartbeatExpiry("", next)).not.toThrow();
+    expect(() => validateHeartbeatExpiry("", "Mention ## Tracked Items here\n- Undated")).toThrow();
+    expect(() => validateHeartbeatExpiry("", "## Tracked Items")).not.toThrow();
+    expect(() => validateHeartbeatExpiry("", "## Other\n- Undated")).not.toThrow();
+  });
+  test("does not use a token on the marker or another line", () => {
+    expect(() => validateHeartbeatExpiry("", "## Tracked Items DELETE 09-30\n- Undated")).toThrow();
+    expect(() =>
+      validateHeartbeatExpiry("", section("- Dated DELETE 09-30", "- Undated")),
+    ).toThrow();
+  });
+  test("legacy matches are one-to-one, even for reordered lines", () => {
+    const old = section("- **Old:** Keep", "- **Other:** Keep");
+    expect(() =>
+      validateHeartbeatExpiry(old, section("- **Other:** Keep", "- **Old:** Updated")),
+    ).not.toThrow();
+    expect(() =>
+      validateHeartbeatExpiry(old, section("- **Old:** Keep", "- **Old:** New")),
+    ).toThrow();
+    expect(() => validateHeartbeatExpiry(old, section("- **Unrelated:** New"))).toThrow();
+  });
+  test("condensing the middle of a legacy line passes", () => {
+    expect(() =>
+      validateHeartbeatExpiry(
+        section("- Check the large queue daily"),
+        section("- Check the queue"),
+      ),
+    ).not.toThrow();
+  });
+  test("dating a legacy item cannot authorize a second undated copy", () => {
+    for (const lines of [
+      ["- **Old:** New", "- **Old:** Updated DELETE 09-30"],
+      ["- **Old:** Updated DELETE 09-30", "- **Old:** New"],
+      ["- Legacy text DELETE 09-30", "- Legacy"],
+    ]) {
+      expect(() =>
+        validateHeartbeatExpiry(section("- **Old:** Original", "- Legacy text"), section(...lines)),
+      ).toThrow();
+    }
+  });
+  test("does not grandfather removal of a date or pin", () => {
+    expect(() =>
+      validateHeartbeatExpiry(section("- **Old:** DELETE 09-30"), section("- **Old:** Undated")),
+    ).toThrow();
+    expect(() => validateHeartbeatExpiry(section("📌 Permanent"), section("Permanent"))).toThrow();
+  });
+});
+
+const dbPath = "./test-heartbeat-expiry.sqlite";
+describe("profile persistence heartbeat gate", () => {
+  const agentId = crypto.randomUUID();
+  beforeAll(async () => {
+    initDb(dbPath);
+    await createAgent({ id: agentId, name: "Expiry test", isLead: false, status: "idle" });
+    // Seed pre-gate legacy state directly in this isolated test database.
+    await getDbClient().run("UPDATE agents SET heartbeatMd = ? WHERE id = ?", [
+      section("- **Legacy:** Old text"),
+      agentId,
+    ]);
+  });
+  afterAll(async () => {
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"])
+      await Bun.file(dbPath + suffix)
+        .delete()
+        .catch(() => {});
+  });
+  test("rejects atomically before profile or version writes", async () => {
+    const before = await getAgentById(agentId);
+    const versionsBefore = await getDbClient().query(
+      "SELECT * FROM context_versions WHERE agentId = ?",
+      [agentId],
+    );
+    await expect(
+      updateAgentProfile(agentId, {
+        description: "Must not land",
+        heartbeatMd: section("- **Legacy:** Old text", "- New undated item"),
+      }),
+    ).rejects.toThrow(HeartbeatExpiryError);
+    expect(await getAgentById(agentId)).toEqual(before);
+    expect(
+      await getDbClient().query("SELECT * FROM context_versions WHERE agentId = ?", [agentId]),
+    ).toEqual(versionsBefore);
+  });
+  test("HTTP returns 400 with the offending line", async () => {
+    const server = createServer(async (req, res) => {
+      try {
+        await handleAgentsRest(
+          req,
+          res,
+          getPathSegments(req.url ?? "/"),
+          parseQueryParams(req.url ?? "/"),
+          agentId,
+        );
+      } catch {
+        res.writeHead(500).end();
+      }
+    });
+    const port = await listenOnFreePort(server);
+    try {
+      const response = await fetch(`http://localhost:${port}/api/agents/${agentId}/profile`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ heartbeatMd: section("- New undated HTTP item") }),
+      });
+      expect(response.status).toBe(400);
+      expect((await response.json()).error).toContain("New undated HTTP item");
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+  test("persists edits, dated additions, pin durables, and deletions", async () => {
+    const next = section("- **Legacy:** Revised", "- Dated DELETE on 09-30", "📌 Durable");
+    expect((await updateAgentProfile(agentId, { heartbeatMd: next }))?.heartbeatMd).toBe(next);
+    expect((await updateAgentProfile(agentId, { heartbeatMd: "" }))?.heartbeatMd).toBe("");
+  });
+  test("drops a stale heartbeat before validating, preserving other updates", async () => {
+    const result = await updateAgentProfile(
+      agentId,
+      { heartbeatMd: section("- Invalid stale item"), description: "Fresh metadata" },
+      undefined,
+      { expectedHashes: { heartbeatMd: "stale" } },
+    );
+    expect(result?.heartbeatMd).toBe("");
+    expect(result?.description).toBe("Fresh metadata");
+  });
+});

package/src/tests/http-api-integration.test.ts

@@ -5,7 +5,7 @@
  * and tests every API endpoint for correct behavior.
  */
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { rm, unlink } from "node:fs/promises";
 import type { Subprocess } from "bun";
 import { Webhook } from "svix";
@@ -388,6 +388,83 @@ describe("Agents", () => {
     expect(unrelated.body.events).toHaveLength(0);
   });
 
+  test("PUT /api/agents/:id/profile — expectedHashes drops a stale field, keeps the rest", async () => {
+    const sha = (v: string) => createHash("sha256").update(v).digest("hex");
+    const base = "# CLAUDE.md\n\nbase the session materialized";
+    const seeded = await put(`/api/agents/${ids.workerAgent}/profile`, {
+      body: { claudeMd: base, changeSource: "self_edit" },
+      agentId: ids.workerAgent,
+    });
+    expect(seeded.status).toBe(200);
+
+    const reconciledClaudeMd = async () =>
+      (
+        await get(
+          `/api/events?${new URLSearchParams({
+            event: "system.profile_sync_reconciled",
+            agentId: ids.workerAgent,
+            dataField: "claudeMd",
+            limit: "100",
+          })}`,
+          { agentId: ids.workerAgent },
+        )
+      ).body.events.length as number;
+    const before = await reconciledClaudeMd();
+
+    // A copy based on something the DB already moved past: dropped, 200, and
+    // the other field of the same sync still lands.
+    const stale = await put(`/api/agents/${ids.workerAgent}/profile`, {
+      body: {
+        claudeMd: "stale copy",
+        toolsMd: "fresh tools",
+        changeSource: "session_sync",
+        expectedHashes: { claudeMd: sha("an older materialization") },
+      },
+      agentId: ids.workerAgent,
+    });
+    expect(stale.status).toBe(200);
+    expect(stale.body.claudeMd).toBe(base);
+    expect(stale.body.toolsMd).toBe("fresh tools");
+    expect(await reconciledClaudeMd()).toBe(before); // not written → not reconciled
+    const conflictEvents = await get(
+      `/api/events?${new URLSearchParams({
+        event: "system.profile_sync_conflict",
+        agentId: ids.workerAgent,
+        dataField: "claudeMd",
+        limit: "1",
+      })}`,
+      { agentId: ids.workerAgent },
+    );
+    expect(conflictEvents.body.events[0]).toMatchObject({
+      event: "system.profile_sync_conflict",
+      status: "skipped",
+      data: {
+        field: "claudeMd",
+        expectedHash: sha("an older materialization"),
+        currentHash: sha(base),
+        changeSource: "session_sync",
+      },
+    });
+
+    // An edit on top of the current value applies.
+    const edited = await put(`/api/agents/${ids.workerAgent}/profile`, {
+      body: {
+        claudeMd: "edited in session",
+        changeSource: "session_sync",
+        expectedHashes: { claudeMd: sha(base) },
+      },
+      agentId: ids.workerAgent,
+    });
+    expect(edited.status).toBe(200);
+    expect(edited.body.claudeMd).toBe("edited in session");
+
+    const malformed = await put(`/api/agents/${ids.workerAgent}/profile`, {
+      body: { claudeMd: "x", expectedHashes: { claudeMd: "not-a-sha256" } },
+      agentId: ids.workerAgent,
+    });
+    expect(malformed.status).toBe(400);
+  });
+
   test("PUT /api/agents/:id/profile — non-existent returns 404", async () => {
     const { status } = await put(`/api/agents/${randomUUID()}/profile`, {
       body: { role: "ghost" },

package/src/tests/pages-public-html.test.ts

@@ -114,6 +114,49 @@ describe("GET /p/:id — HTML public path", () => {
     expect(text).toContain("--swarm-text: #111827");
   });
 
+  for (const authMode of ["public", "authed", "password"]) {
+    test(`SVG bytes and security headers survive ${authMode} access`, async () => {
+      const svg = '<svg xmlns="http://www.w3.org/2000/svg"><text>★ &amp; stars</text></svg>\n';
+      const post = await fetch(`${BASE}/api/pages`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          slug: `svg-${authMode}`,
+          title: "Stars",
+          body: svg,
+          contentType: "image/svg+xml",
+          authMode,
+          ...(authMode === "password" ? { password: "test-key" } : {}),
+        }),
+      });
+      expect(post.status).toBe(201);
+      const { id } = (await post.json()) as { id: string };
+      let cookie = "";
+      if (authMode !== "public") {
+        expect((await fetch(`${BASE}/p/${id}`)).status).toBe(401);
+        if (authMode === "authed") {
+          const launch = await fetch(`${BASE}/api/pages/${id}/launch`, { method: "POST", headers });
+          expect(launch.status).toBe(204);
+          cookie = launch.headers.get("set-cookie")!.split(";")[0]!;
+        }
+      }
+      const query = authMode === "password" ? "?key=test-key&print=1" : "?print=1";
+      const res = await fetch(`${BASE}/p/${id}${query}`, {
+        headers: cookie ? { Cookie: cookie } : {},
+      });
+      expect(res.status).toBe(200);
+      expect(await res.text()).toBe(svg);
+      expect(res.headers.get("content-type")).toBe("image/svg+xml");
+      expect(res.headers.get("x-content-type-options")).toBe("nosniff");
+      expect(res.headers.get("content-security-policy")).toBe(
+        "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+      );
+      expect(res.headers.get("cache-control")).toBe(
+        authMode === "public" ? "public, max-age=1800" : "private, no-store",
+      );
+    });
+  }
+
   test("CSP frame ancestors include deprecated DASHBOARD_URL alias", async () => {
     const prevApp = process.env.APP_URL;
     const prevDashboard = process.env.DASHBOARD_URL;

package/src/tests/pages-svg-migration.test.ts

@@ -0,0 +1,42 @@
+import { Database } from "bun:sqlite";
+import { expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+
+const migration = (name: string) =>
+  readFileSync(new URL(`../be/migrations/${name}`, import.meta.url), "utf8");
+
+test("SVG migration preserves existing rows, history, indexes and asset key triggers", () => {
+  const db = new Database(":memory:");
+  try {
+    db.exec("CREATE TABLE users (id TEXT PRIMARY KEY)");
+    db.exec(migration("059_pages.sql"));
+    db.exec(migration("060_page_versions.sql"));
+    db.exec("ALTER TABLE pages ADD COLUMN view_count INTEGER NOT NULL DEFAULT 0");
+    db.exec("ALTER TABLE pages ADD COLUMN created_by TEXT REFERENCES users(id)");
+    db.exec("ALTER TABLE pages ADD COLUMN updated_by TEXT REFERENCES users(id)");
+    db.exec(migration("086_pages_default_authed.sql"));
+    db.exec("ALTER TABLE pages ADD COLUMN \"key\" TEXT NOT NULL DEFAULT 'shared/'");
+    db.exec("INSERT INTO users VALUES ('user')");
+    db.exec(`INSERT INTO pages (id,agentId,slug,title,contentType,body,authMode,passwordHash,view_count,created_by,updated_by,"key")
+      VALUES ('page','agent','stars','Stars','text/html','original','password','hash',42,'user','user','personal/user/stars/')`);
+    db.exec("INSERT INTO page_versions (pageId,version,snapshot) VALUES ('page',1,'{}')");
+    const before = db.query("SELECT * FROM pages").get();
+    db.transaction(() => db.exec(migration("148_pages_svg.sql")))();
+    db.exec("PRAGMA foreign_keys=ON");
+    expect(db.query("SELECT * FROM pages").get()).toEqual(before);
+    expect(db.query("SELECT * FROM page_versions").all()).toHaveLength(1);
+    expect(db.query("PRAGMA foreign_key_check").all()).toEqual([]);
+    db.exec("UPDATE pages SET contentType='image/svg+xml'");
+    expect(() => db.exec("UPDATE pages SET contentType='text/plain'")).toThrow();
+    expect(() => db.exec("UPDATE pages SET \"key\"='INVALID'")).toThrow(
+      "invalid asset namespace key",
+    );
+    expect(
+      db.query("SELECT name FROM sqlite_master WHERE type='index' AND tbl_name='pages'").all(),
+    ).toHaveLength(6);
+    db.exec("DELETE FROM pages");
+    expect(db.query("SELECT * FROM page_versions").all()).toHaveLength(0);
+  } finally {
+    db.close();
+  }
+});

package/src/tests/preload.ts

@@ -14,6 +14,8 @@ import {
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { closeDb, getDb, initDb } from "../be/db";
+// Populate the registry before hashing the template cache; runtime boot loads this lazily.
+import "../be/seed-prompt-templates";
 import { getAllTemplateDefinitions } from "../prompts/registry";
 import { clearVolatileSecretsForTesting } from "../utils/secret-scrubber";
 
@@ -102,6 +104,7 @@ function migrationTemplateCacheKey(): string {
   const inputs = [
     join(import.meta.dir, "preload.ts"),
     join(import.meta.dir, "../be/db.ts"),
+    join(import.meta.dir, "../be/db/runtime.ts"),
     join(import.meta.dir, "../be/seed-prompt-templates.ts"),
   ];
   const migrationsDir = join(import.meta.dir, "../be/migrations");
@@ -114,7 +117,7 @@ function migrationTemplateCacheKey(): string {
     hash.update("\n");
   }
   // seedDefaultTemplates bakes the prompt-template registry into the DB; the
-  // registry is populated by side-effect imports (db.ts -> seed-prompt-templates),
+  // registry is populated by the explicit seed-prompt-templates import above,
   // so its current content is hashed directly instead of guessing source files.
   hash.update(JSON.stringify(getAllTemplateDefinitions()));
   return hash.digest("hex").slice(0, 32);

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

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { prependContextPreamble } from "../commands/context-preamble";
 import {
   contentSha256,
   fetchProfileSyncRejectionBanner,
@@ -86,6 +87,21 @@ describe("profile sync rejection session warning", () => {
     expect(result.injected).toBeTrue();
     expect(result.prompt).toContain("PERSISTED PROFILE SYNC REJECTION");
     expect(result.prompt).toEndWith("ORIGINAL TASK PROMPT");
+
+    const context = "\n## Prior Conversation Context\nParent evidence\n\n";
+    const taskPrompt = "/work-on-task child-id\n\nTask: follow up";
+    const followUp = await prependProfileSyncRejectionBanner(
+      prependContextPreamble(taskPrompt, context),
+      { apiUrl: "https://api.example.test", apiKey: "secret-key", agentId: "agent-1" },
+      fetchImpl,
+    );
+    expect(followUp.prompt).toStartWith("/work-on-task child-id\n");
+    expect(followUp.prompt).toContain(context);
+    expect(followUp.prompt).toContain("PERSISTED PROFILE SYNC REJECTION");
+    expect(followUp.prompt).toEndWith("Task: follow up");
+    expect(followUp.prompt.indexOf("PERSISTED PROFILE SYNC REJECTION")).toBeLessThan(
+      followUp.prompt.indexOf("## Prior Conversation Context"),
+    );
   });
 
   test("stops warning after the stored field changes", async () => {

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

@@ -1,8 +1,13 @@
 import { describe, expect, spyOn, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import {
   buildIdentityPayload,
   buildIndependentIdentityPayloads,
+  CLAUDE_MD_LINEAGE_PATH,
   CLAUDE_MD_PATH,
+  claudeMdPendingRecord,
   collectProfilePayloads,
   contentSha256,
   extractSetupScriptContent,
@@ -23,6 +28,7 @@ import {
 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";
+import { holdFileLock } from "./fixtures/hold-file-lock";
 
 const MARKER_START = "# === Agent-managed setup (from DB) ===";
 const MARKER_END = "# === End agent-managed setup ===";
@@ -478,6 +484,35 @@ describe("postProfileUpdate (non-2xx is surfaced, not swallowed)", () => {
 });
 
 describe("syncProfileFilesToServer (orchestration is non-fatal)", () => {
+  test("skips the personal CLAUDE.md, reading nothing, while its lock is held", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "claude-md-lock-"));
+    const lockPath = join(dir, "CLAUDE.md.lock");
+    const release = await holdFileLock(lockPath);
+    const sent: string[] = [];
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const fetchImpl = (async (_url: string, init?: RequestInit) => {
+      sent.push(String(init?.body));
+      return new Response("{}", { status: 200 });
+    }) as typeof fetch;
+    try {
+      await syncProfileFilesToServer({
+        agentId: "agent-1",
+        apiUrl: "https://api.example.test",
+        apiKey: "secret-key",
+        changeSource: "session_sync",
+        fields: ["claude"],
+        claudeMdLock: { path: lockPath, waitMs: 100 },
+        fetchImpl,
+      });
+      expect(sent).toEqual([]);
+      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("no CLAUDE.md lock (busy)"));
+    } finally {
+      await release();
+      warnSpy.mockRestore();
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
   test("resolves without throwing even when every POST fails", async () => {
     const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
     const errSpy = spyOn(console, "error").mockImplementation(() => {});
@@ -490,6 +525,7 @@ describe("syncProfileFilesToServer (orchestration is non-fatal)", () => {
           apiKey: "secret-key",
           changeSource: "session_sync",
           // No files on a CI box → typically no payloads; still must never throw.
+          claudeMdLock: { path: join(tmpdir(), `claude-md-${crypto.randomUUID()}.lock`) },
           fetchImpl,
         }),
       ).resolves.toBeUndefined();
@@ -646,6 +682,96 @@ describe("collectProfilePayloads (baseline integration)", () => {
     const payloads = await collectProfilePayloads(["claude"], "session_sync", files);
     expect(payloads).toHaveLength(1);
     expect(payloads[0]?.body.claudeMd).toBe("modified claude md");
+    // The personal file is hook-owned and can hold any session's copy: the
+    // runner's backstop sends its boot baseline as the compare-and-set token.
+    expect(payloads[0]?.body.expectedHashes).toEqual({ claudeMd: contentSha256("original") });
+  });
+
+  test("the runner backstop skips content the Claude hook itself wrote", async () => {
+    // After a Stop the hook has restored the `.bak`: the file holds a copy a
+    // hook wrote (this session's or a sibling's), not an edit.
+    const files = reader({
+      [CLAUDE_MD_PATH]: "restored by a hook",
+      [IDENTITY_BASELINES_PATH]: JSON.stringify({ claudeMd: contentSha256("boot") }),
+      [CLAUDE_MD_LINEAGE_PATH]: JSON.stringify({
+        written: contentSha256("restored by a hook"),
+        base: contentSha256("restored by a hook"),
+      }),
+    });
+
+    expect(await collectProfilePayloads(["claude"], "session_sync", files)).toEqual([]);
+  });
+
+  test("the runner backstop does not push when the lineage record is unreadable", async () => {
+    const files = reader({
+      [CLAUDE_MD_PATH]: "edited",
+      [IDENTITY_BASELINES_PATH]: JSON.stringify({ claudeMd: contentSha256("boot") }),
+      [CLAUDE_MD_LINEAGE_PATH]: "{not json",
+    });
+
+    expect(await collectProfilePayloads(["claude"], "session_sync", files)).toEqual([]);
+  });
+
+  test("the runner backstop does not push when the record holds a non-sha256 value", async () => {
+    const files = reader({
+      [CLAUDE_MD_PATH]: "hook materialization",
+      [IDENTITY_BASELINES_PATH]: JSON.stringify({ claudeMd: contentSha256("boot") }),
+      [CLAUDE_MD_LINEAGE_PATH]: JSON.stringify({ written: "not-a-sha256", base: null }),
+    });
+
+    expect(await collectProfilePayloads(["claude"], "session_sync", files)).toEqual([]);
+  });
+
+  test("the runner backstop does not push while a hook write is pending", async () => {
+    // A hook write whose lineage never landed leaves the record marked pending:
+    // whatever is on disk then counts as hook-written, for the backstop too.
+    const files = reader({
+      [CLAUDE_MD_PATH]: "edited",
+      [IDENTITY_BASELINES_PATH]: JSON.stringify({ claudeMd: contentSha256("boot") }),
+      [CLAUDE_MD_LINEAGE_PATH]: claudeMdPendingRecord(contentSha256("materialized")),
+    });
+
+    expect(await collectProfilePayloads(["claude"], "session_sync", files)).toEqual([]);
+  });
+
+  test("the runner backstop sends an edit against the base the hook recorded", async () => {
+    const files = reader({
+      [CLAUDE_MD_PATH]: "edited",
+      [IDENTITY_BASELINES_PATH]: JSON.stringify({ claudeMd: contentSha256("boot") }),
+      [CLAUDE_MD_LINEAGE_PATH]: JSON.stringify({
+        written: contentSha256("materialized"),
+        base: contentSha256("materialized"),
+      }),
+    });
+
+    const payloads = await collectProfilePayloads(["claude"], "session_sync", files);
+    expect(payloads.map((p) => p.body)).toEqual([
+      {
+        claudeMd: "edited",
+        changeSource: "session_sync",
+        expectedHashes: { claudeMd: contentSha256("materialized") },
+      },
+    ]);
+  });
+
+  test("session_sync of the workspace CLAUDE.md stays unconditional", async () => {
+    // Non-Claude harnesses edit /workspace/CLAUDE.md directly and nothing
+    // rematerializes it mid-life, so the boot baseline is not a valid base.
+    const baselines: IdentityBaselines = { claudeMd: contentSha256("original") };
+    const files = reader({
+      [WORKSPACE_CLAUDE_MD_PATH]: "modified workspace md",
+      [IDENTITY_BASELINES_PATH]: JSON.stringify(baselines),
+    });
+
+    const payloads = await collectProfilePayloads(
+      ["claude"],
+      "session_sync",
+      files,
+      WORKSPACE_CLAUDE_MD_PATH,
+    );
+    expect(payloads.map((p) => p.body)).toEqual([
+      { claudeMd: "modified workspace md", changeSource: "session_sync" },
+    ]);
   });
 
   test("session_sync proceeds normally when baselines file is missing", async () => {

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

@@ -215,11 +215,27 @@ describe("Session templates: MUST pointers", () => {
     );
   });
 
-  test("the lead contract names the renamed desplega commands", () => {
+  test("the worker contract names the four task endings", () => {
+    const result = resolveTemplate("system.agent.worker", {});
+    expect(result.text).toContain("The task has four endings.");
+    for (const ending of ["`completed`", "`defer-task`", "`request-human-input`", "`failed`"]) {
+      expect(result.text).toContain(ending);
+    }
+  });
+
+  test("the lead contract names the delegation tools", () => {
+    const result = resolveTemplate("system.agent.lead", {});
+    expect(result.text).toContain(
+      "Delegate with `send-task`. Read a child's result with `get-task-details`.",
+    );
+  });
+
+  test("the lead contract names the desplega skills, not slash commands", () => {
     const result = resolveTemplate("system.agent.lead", {});
-    expect(result.text).toContain("/researching");
-    expect(result.text).toContain("/planning");
-    expect(result.text).toContain("/implementing");
+    expect(result.text).toContain("`researching` skill");
+    expect(result.text).toContain("`planning` skill");
+    expect(result.text).toContain("`implementing` skill");
+    expect(result.text).not.toContain("/researching");
   });
 });