@desplega.ai/agent-swarm 2.7.5 → 2.7.7

package/src/tests/identity-field-budget.test.ts

@@ -179,7 +179,7 @@ describe("Stop-hook profile sync visibility", () => {
             throw new Error("network unavailable");
           }) as typeof fetch,
         }),
-      ).resolves.toBeUndefined();
+      ).resolves.toBe(false);
       expect(String(errorSpy.mock.calls[0]?.[0])).toContain(
         "claudeMd profile sync errored: network unavailable",
       );

package/src/tests/internal-ai/credentials.test.ts

@@ -3,6 +3,7 @@ import {
   DEFAULT_MODEL,
   type ResolveCredentialOptions,
   resolveCredential,
+  resolveCredentials,
 } from "../../utils/internal-ai/credentials.js";
 
 /**
@@ -331,3 +332,64 @@ describe("resolveCredential", () => {
     }
   });
 });
+
+describe("resolveCredentials", () => {
+  test("returns every credential in precedence order", async () => {
+    const creds = await resolveCredentials(
+      makeOpts({
+        env: {
+          OPENROUTER_API_KEY: "example-or",
+          ANTHROPIC_API_KEY: "example-ant",
+          OPENAI_API_KEY: "example-oai",
+          CLAUDE_CODE_OAUTH_TOKEN: "example-claude",
+        },
+      }),
+    );
+    expect(creds.map((cred) => cred.kind)).toEqual([
+      "openrouter",
+      "anthropic",
+      "openai",
+      "claude-cli",
+    ]);
+  });
+
+  test("`kinds` restricts the lookup and `limit` stops early", async () => {
+    const env = { OPENROUTER_API_KEY: "example-or", OPENAI_API_KEY: "example-oai" };
+    const onlyOpenai = await resolveCredentials({ ...makeOpts({ env }), kinds: ["openai"] });
+    expect(onlyOpenai.map((cred) => cred.kind)).toEqual(["openai"]);
+
+    const first = await resolveCredentials({ ...makeOpts({ env }), limit: 1 });
+    expect(first.map((cred) => cred.kind)).toEqual(["openrouter"]);
+
+    const none = await resolveCredentials({ ...makeOpts({ env }), kinds: ["anthropic"] });
+    expect(none).toEqual([]);
+  });
+
+  test("the codex probe runs only when its kind is requested", async () => {
+    let probed = 0;
+    const base = {
+      env: { OPENROUTER_API_KEY: "example-or" },
+      apiUrl: "http://localhost:3013",
+      apiKey: "k",
+      _getValidCodexOAuth: async () => {
+        probed++;
+        return { access: "a", refresh: "r", expires: Date.now() + 60_000, accountId: "acct" };
+      },
+      _getOAuthApiKey: async () => ({ apiKey: "codex-access" }),
+    };
+    const envOnly = await resolveCredentials({
+      ...makeOpts(base),
+      kinds: ["openrouter", "openai"],
+    });
+    expect(envOnly.map((cred) => cred.kind)).toEqual(["openrouter"]);
+    expect(probed).toBe(0);
+
+    const codex = await resolveCredentials({ ...makeOpts(base), kinds: ["openai-codex"] });
+    expect(codex.map((cred) => cred.kind)).toEqual(["openai-codex"]);
+    expect(probed).toBe(1);
+
+    const all = await resolveCredentials(makeOpts(base));
+    expect(all.map((cred) => cred.kind)).toEqual(["openrouter", "openai-codex"]);
+    expect(probed).toBe(2);
+  });
+});

package/src/tests/internal-ai/task-title.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, test } from "bun:test";
+import type { completeStructuredWithModel } from "../../utils/internal-ai/complete-structured.js";
+import type {
+  CredentialKind,
+  ResolvedCredential,
+  resolveCredentials,
+} from "../../utils/internal-ai/credentials.js";
+import {
+  buildTaskTitlePlan,
+  generateTaskTitle,
+  kindForModelString,
+  normalizeTaskTitle,
+  prepareTaskTextForTitle,
+  TASK_TITLE_MAX_CHARS,
+  TASK_TITLE_MAX_TASK_CHARS,
+  TASK_TITLE_MODEL_CANDIDATES,
+  TASK_TITLE_MODEL_ENV,
+} from "../../utils/internal-ai/task-title.js";
+
+const LONG_TASK =
+  "Investigate why the nightly Playwright suite times out on the sessions page after the sidebar redesign and fix the flake.";
+
+function credential(kind: CredentialKind): ResolvedCredential {
+  return kind === "claude-cli"
+    ? { kind, modelDefault: "haiku" }
+    : { kind, apiKey: `key-${kind}`, modelDefault: `${kind}/default` };
+}
+
+/** `resolveCredentials` stub that offers exactly `kinds` and records every lookup. */
+function resolver(kinds: CredentialKind[], calls: CredentialKind[][] = []) {
+  const resolve: typeof resolveCredentials = async (opts) => {
+    const wanted = [...(opts?.kinds ?? [])];
+    calls.push(wanted);
+    return wanted.filter((kind) => kinds.includes(kind)).map(credential);
+  };
+  return { resolve, calls };
+}
+
+type CompleteFn = typeof completeStructuredWithModel;
+
+/** `completeStructuredWithModel` stub keyed by model string; absent = failure (null). */
+function completer(answers: Record<string, string | Error>, models: string[] = []) {
+  const complete: CompleteFn = async (opts) => {
+    const model = opts._credentialOverride?.modelDefault ?? "<none>";
+    models.push(model);
+    const answer = answers[model];
+    if (answer instanceof Error) throw answer;
+    if (answer === undefined) return null;
+    return { data: { title: answer }, model };
+  };
+  return { complete, models };
+}
+
+describe("normalizeTaskTitle", () => {
+  test("collapses whitespace, strips quotes, prefix, markdown and trailing punctuation", () => {
+    expect(normalizeTaskTitle('  "Fix   sessions sidebar flake."  ')).toBe(
+      "Fix sessions sidebar flake",
+    );
+    expect(normalizeTaskTitle("Title: **Rotate Slack token**")).toBe("Rotate Slack token");
+    expect(normalizeTaskTitle("“Add retry to poller”…")).toBe("Add retry to poller");
+    expect(normalizeTaskTitle("`Bump bun to 1.4`")).toBe("Bump bun to 1.4");
+  });
+
+  test("keeps question marks and inner punctuation", () => {
+    expect(normalizeTaskTitle("Why does the poller stall?")).toBe("Why does the poller stall?");
+    expect(normalizeTaskTitle("Migrate agent-fs 0.16.3 pins")).toBe("Migrate agent-fs 0.16.3 pins");
+  });
+
+  test("cuts long titles at a word boundary under the limit", () => {
+    const words = Array.from({ length: 40 }, (_, i) => `word${i}`).join(" ");
+    const title = normalizeTaskTitle(words);
+    expect(title.length).toBeLessThanOrEqual(TASK_TITLE_MAX_CHARS);
+    expect(title.endsWith("word")).toBe(false);
+    expect(words.startsWith(title)).toBe(true);
+  });
+
+  test("returns an empty string when nothing usable remains", () => {
+    expect(normalizeTaskTitle('""')).toBe("");
+    expect(normalizeTaskTitle(" ... ")).toBe("");
+  });
+});
+
+describe("prepareTaskTextForTitle", () => {
+  test("drops the sibling-awareness block and collapses blank lines", () => {
+    const task = `<sibling_tasks_in_progress>\n- other\n</sibling_tasks_in_progress>\n\n\n\nFix the login bug\n\n\n\nin the auth module`;
+    expect(prepareTaskTextForTitle(task)).toBe("Fix the login bug\n\nin the auth module");
+  });
+
+  test("keeps a prompt without the block and truncates long prompts", () => {
+    expect(prepareTaskTextForTitle("  hello\r\nworld ")).toBe("hello\nworld");
+    const long = "x".repeat(TASK_TITLE_MAX_TASK_CHARS + 500);
+    const prepared = prepareTaskTextForTitle(long);
+    expect(prepared.length).toBe(TASK_TITLE_MAX_TASK_CHARS + 2);
+    expect(prepared.endsWith(" …")).toBe(true);
+  });
+});
+
+describe("buildTaskTitlePlan", () => {
+  test("default plan is the candidate table", () => {
+    expect(buildTaskTitlePlan({})).toBe(TASK_TITLE_MODEL_CANDIDATES);
+  });
+
+  test("a pinned model moves its provider first and the model to the front", () => {
+    const plan = buildTaskTitlePlan({ [TASK_TITLE_MODEL_ENV]: "openai/gpt-5-nano" });
+    expect(plan[0]).toEqual({ kind: "openai", models: ["openai/gpt-5-nano", "openai/gpt-6-luna"] });
+    expect(plan.slice(1).map((group) => group.kind)).toEqual([
+      "openrouter",
+      "anthropic",
+      "openai-codex",
+      "claude-cli",
+    ]);
+  });
+
+  test("a pinned model outside the table is still tried first", () => {
+    const plan = buildTaskTitlePlan({ [TASK_TITLE_MODEL_ENV]: "anthropic/claude-haiku-4-5" });
+    expect(plan[0]?.models).toEqual(["anthropic/claude-haiku-4-5", "anthropic/claude-haiku-5-5"]);
+  });
+
+  test("a bare alias pins the claude CLI; an unsupported provider is ignored", () => {
+    expect(buildTaskTitlePlan({ [TASK_TITLE_MODEL_ENV]: "sonnet" })[0]).toEqual({
+      kind: "claude-cli",
+      models: ["sonnet", "haiku"],
+    });
+    expect(buildTaskTitlePlan({ [TASK_TITLE_MODEL_ENV]: "google/gemini-2.5-flash-lite" })).toBe(
+      TASK_TITLE_MODEL_CANDIDATES,
+    );
+  });
+
+  test("kindForModelString maps provider prefixes", () => {
+    expect(kindForModelString("openrouter/deepseek/deepseek-v4.1-flash")).toBe("openrouter");
+    expect(kindForModelString("openai-codex/gpt-6-luna")).toBe("openai-codex");
+    expect(kindForModelString("haiku")).toBe("claude-cli");
+    expect(kindForModelString("mistral/ministral-3b")).toBeNull();
+  });
+});
+
+describe("generateTaskTitle", () => {
+  test("short prompts are skipped before any credential lookup", async () => {
+    const { resolve, calls } = resolver(["openrouter"]);
+    const { complete, models } = completer({});
+    const result = await generateTaskTitle({
+      task: "fix the login bug",
+      env: {},
+      _resolveCredentials: resolve,
+      _completeStructured: complete,
+    });
+    expect(result).toEqual({ ok: false, reason: "short-task" });
+    expect(calls).toEqual([]);
+    expect(models).toEqual([]);
+  });
+
+  test("uses the first provider with a credential and its cheapest model", async () => {
+    const { resolve } = resolver(["anthropic", "openai"]);
+    const { complete, models } = completer({
+      "anthropic/claude-haiku-5-5": "Fix nightly Playwright timeout on sessions page",
+    });
+    const result = await generateTaskTitle({
+      task: LONG_TASK,
+      env: {},
+      _resolveCredentials: resolve,
+      _completeStructured: complete,
+    });
+    expect(result).toEqual({
+      ok: true,
+      title: "Fix nightly Playwright timeout on sessions page",
+      model: "anthropic/claude-haiku-5-5",
+      kind: "anthropic",
+    });
+    expect(models).toEqual(["anthropic/claude-haiku-5-5"]);
+  });
+
+  test("falls through models, then providers, on null results and thrown errors", async () => {
+    const { resolve } = resolver(["openrouter", "openai"]);
+    const { complete, models } = completer({
+      "openrouter/deepseek/deepseek-v4.1-flash": new Error("429 rate limited"),
+      // claude-haiku-5.5 absent → null
+      "openrouter/openai/gpt-6-luna": "   ",
+      "openai/gpt-6-luna": "Sessions page Playwright flake",
+    });
+    const result = await generateTaskTitle({
+      task: LONG_TASK,
+      env: {},
+      _resolveCredentials: resolve,
+      _completeStructured: complete,
+    });
+    expect(result).toEqual({
+      ok: true,
+      title: "Sessions page Playwright flake",
+      model: "openai/gpt-6-luna",
+      kind: "openai",
+    });
+    expect(models).toEqual([
+      "openrouter/deepseek/deepseek-v4.1-flash",
+      "openrouter/anthropic/claude-haiku-5.5",
+      "openrouter/openai/gpt-6-luna",
+      "openai/gpt-6-luna",
+    ]);
+  });
+
+  test("resolves one credential kind at a time and stops before the codex probe when an earlier provider answers", async () => {
+    const { resolve, calls } = resolver(["openrouter", "openai-codex"]);
+    const { complete } = completer({ "openrouter/deepseek/deepseek-v4.1-flash": "A title" });
+    await generateTaskTitle({
+      task: LONG_TASK,
+      env: {},
+      apiUrl: "http://127.0.0.1:1",
+      apiKey: "k",
+      _resolveCredentials: resolve,
+      _completeStructured: complete,
+    });
+    expect(calls).toEqual([["openrouter"]]);
+  });
+
+  test("reports no-credentials when nothing resolves and all-models-failed otherwise", async () => {
+    const none = resolver([]);
+    const silent = completer({});
+    expect(
+      await generateTaskTitle({
+        task: LONG_TASK,
+        env: {},
+        _resolveCredentials: none.resolve,
+        _completeStructured: silent.complete,
+      }),
+    ).toEqual({ ok: false, reason: "no-credentials" });
+    // Every kind was asked exactly once, in precedence order.
+    expect(none.calls.map((call) => call[0])).toEqual(
+      TASK_TITLE_MODEL_CANDIDATES.map((group) => group.kind),
+    );
+
+    const some = resolver(["claude-cli"]);
+    expect(
+      await generateTaskTitle({
+        task: LONG_TASK,
+        env: {},
+        _resolveCredentials: some.resolve,
+        _completeStructured: silent.complete,
+      }),
+    ).toEqual({ ok: false, reason: "all-models-failed" });
+    expect(silent.models).toEqual(["haiku"]);
+  });
+
+  test("the pinned model runs first and the credential override carries it", async () => {
+    const { resolve } = resolver(["openrouter", "openai"]);
+    let seenOverride: ResolvedCredential | undefined;
+    const complete: CompleteFn = async (opts) => {
+      seenOverride = opts._credentialOverride;
+      return { data: { title: "Pinned" }, model: "openai/gpt-5-nano" };
+    };
+    const result = await generateTaskTitle({
+      task: LONG_TASK,
+      env: { [TASK_TITLE_MODEL_ENV]: "openai/gpt-5-nano" },
+      _resolveCredentials: resolve,
+      _completeStructured: complete,
+    });
+    expect(result).toEqual({
+      ok: true,
+      title: "Pinned",
+      model: "openai/gpt-5-nano",
+      kind: "openai",
+    });
+    expect(seenOverride).toEqual({
+      kind: "openai",
+      apiKey: "key-openai",
+      modelDefault: "openai/gpt-5-nano",
+    });
+  });
+
+  test("an aborted signal stops the walk", async () => {
+    const { resolve } = resolver(["openrouter"]);
+    const { complete, models } = completer({ "openrouter/deepseek/deepseek-v4.1-flash": "T" });
+    const controller = new AbortController();
+    controller.abort();
+    const result = await generateTaskTitle({
+      task: LONG_TASK,
+      env: {},
+      signal: controller.signal,
+      _resolveCredentials: resolve,
+      _completeStructured: complete,
+    });
+    expect(result).toEqual({ ok: false, reason: "no-credentials" });
+    expect(models).toEqual([]);
+  });
+});

package/src/tests/list-total-cache.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { createListTotalCache } from "../http/list-total-cache";
+import { createListTotalCache, LIST_TOTAL_TTL_MS } from "../http/list-total-cache";
 
 function counter(values: number[]) {
   let calls = 0;
@@ -10,7 +10,7 @@ function counter(values: number[]) {
 }
 
 describe("list total cache", () => {
-  test("page 1 always counts; later pages reuse its count", async () => {
+  test("page 1 always counts by default; later pages reuse its count", async () => {
     const cache = createListTotalCache();
     const count = counter([10, 11, 12]);
 
@@ -24,6 +24,31 @@ describe("list total cache", () => {
     expect(count.calls()).toBe(2);
   });
 
+  test("page 1 polls within the first-page TTL share one count", async () => {
+    const cache = createListTotalCache(LIST_TOTAL_TTL_MS, 50);
+    const count = counter([10, 11]);
+    expect(await cache.get({ q: "a" }, 0, count.compute)).toBe(10);
+    expect(await cache.get({ q: "a" }, 0, count.compute)).toBe(10);
+    expect(count.calls()).toBe(1);
+    await Bun.sleep(60);
+    expect(await cache.get({ q: "a" }, 0, count.compute)).toBe(11);
+    expect(count.calls()).toBe(2);
+  });
+
+  test("with a first-page TTL, concurrent page 1 requests share an in-flight count", async () => {
+    const cache = createListTotalCache(LIST_TOTAL_TTL_MS, 1000);
+    let calls = 0;
+    const compute = async () => {
+      calls++;
+      await Bun.sleep(5);
+      return 4;
+    };
+    expect(await Promise.all([cache.get({}, 0, compute), cache.get({}, 0, compute)])).toEqual([
+      4, 4,
+    ]);
+    expect(calls).toBe(1);
+  });
+
   test("a cold later page counts, so total is always set", async () => {
     const cache = createListTotalCache();
     const count = counter([7]);

package/src/tests/memory-fts-populate.test.ts

@@ -2,8 +2,8 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import { closeDb, createAgent, getDb, getDbClient, initDb } from "../be/db";
 import {
-  FTS_DELETE_EXTRA_SQL,
-  FTS_MISSING_IDS_SQL,
+  FTS_SCAN_BATCH_SQL,
+  MEMORY_ID_BATCH_SQL,
   SqliteMemoryStore,
 } from "../be/memory/providers/sqlite-store";
 
@@ -62,16 +62,18 @@ describe("memory_fts boot backfill", () => {
     // Positive control: the old anti-join scans memory_fts once per memory.
     expect(planOf(QUADRATIC_BACKFILL_SQL).join(" | ")).toContain("CORRELATED");
 
-    for (const sql of [FTS_MISSING_IDS_SQL, FTS_DELETE_EXTRA_SQL]) {
-      const plan = planOf(sql).join(" | ");
-      expect(plan).not.toContain("CORRELATED");
-      // Exactly one pass over memory_fts per statement.
-      expect(plan.match(/SCAN memory_fts/g)?.length).toBe(1);
-    }
+    // Each batch seeks a rowid range of one table. The orphan check is a
+    // lookup on the agent_memory primary key, never a scan of memory_fts.
+    const scan = planOf(FTS_SCAN_BATCH_SQL.replace(/\?/g, "0")).join(" | ");
+    expect(scan).toMatch(/SCAN memory_fts VIRTUAL TABLE INDEX \d+:>/);
+    expect(scan.match(/memory_fts/g)?.length).toBe(1);
+    expect(scan).toContain("SEARCH m USING COVERING INDEX sqlite_autoindex_agent_memory_1 (id=?)");
+    const ids = planOf(MEMORY_ID_BATCH_SQL.replace(/\?/g, "0")).join(" | ");
+    expect(ids).toContain("SEARCH agent_memory USING INTEGER PRIMARY KEY (rowid>?)");
   });
 
   test("a new store backfills missing rows across batches and drops orphans", async () => {
-    const total = 1050; // crosses two 500-row batch boundaries
+    const total = 1050; // crosses two 500-row insert batches and one 1000-row scan batch
     const seed = await store.store({
       agentId,
       scope: "agent",

package/src/tests/memory-retrieval-purge.test.ts

@@ -0,0 +1,80 @@
+import { afterAll, beforeAll, describe, expect, spyOn, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, getDb, getDbClient, initDb } from "../be/db";
+import { purgeStaleSearchRetrievals, startMemoryGc, stopMemoryGc } from "../http/memory";
+
+const TEST_DB_PATH = "./test-memory-retrieval-purge.sqlite";
+const DAY = 24 * 60 * 60 * 1000;
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"])
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => undefined);
+}
+
+async function insertRetrieval(id: string, eventType: string, ageDays: number): Promise<void> {
+  await getDbClient().run(
+    `INSERT INTO memory_retrieval (id, agentId, memoryId, retrievedAt, eventType)
+     VALUES (?, 'agent-1', 'memory-1', ?, ?)`,
+    [id, new Date(Date.now() - ageDays * DAY).toISOString(), eventType],
+  );
+}
+
+describe("purgeStaleSearchRetrievals", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    closeDb();
+    await removeDbFiles();
+  });
+
+  test("deletes stale search rows in batches and keeps fresh and get rows", async () => {
+    for (let i = 0; i < 5; i++) await insertRetrieval(`stale-search-${i}`, "search", 120);
+    await insertRetrieval("fresh-search", "search", 10);
+    await insertRetrieval("stale-get", "get", 120);
+
+    const run = spyOn(getDbClient(), "run");
+    let purged: number;
+    let calls: (typeof run.mock.calls)[number][];
+    try {
+      purged = await purgeStaleSearchRetrievals(2);
+      calls = [...run.mock.calls];
+    } finally {
+      run.mockRestore();
+    }
+    expect(purged).toBe(5);
+    // Batches of 2: 2 + 2 + 1, and the short batch ends the loop.
+    expect(calls).toHaveLength(3);
+
+    const left = await getDbClient().query<{ id: string }>(
+      "SELECT id FROM memory_retrieval ORDER BY id",
+    );
+    expect(left.map((row) => row.id)).toEqual(["fresh-search", "stale-get"]);
+
+    // Without sqlite_stat1 the plan must stay on the retrievedAt range, not
+    // read every search row through the eventType index.
+    const [sql, params] = calls[0]!;
+    const plan = getDb()
+      .query<{ detail: string }, any[]>(`EXPLAIN QUERY PLAN ${sql}`)
+      .all(...((params ?? []) as any[]))
+      .map((row) => row.detail)
+      .join("\n");
+    expect(plan).toContain("USING INDEX idx_memret_retrieved_at (retrievedAt<?)");
+    expect(plan).not.toContain("idx_memret_event_type");
+  });
+});
+
+describe("startMemoryGc", () => {
+  test("defers the first purge off the boot path", async () => {
+    const timeout = spyOn(globalThis, "setTimeout");
+    try {
+      await startMemoryGc(60 * 60 * 1000, 120_000);
+      expect(timeout.mock.calls.some(([, ms]) => ms === 120_000)).toBe(true);
+    } finally {
+      stopMemoryGc();
+      timeout.mockRestore();
+    }
+  });
+});

package/src/tests/merge-gate-detect-changes.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Runs the merge gate's "Compute per-domain change flags" step, verbatim from
+ * .github/workflows/merge-gate.yml, against throwaway git repos.
+ *
+ * Regression: a rename from a covered path to an excluded one (src/x.ts ->
+ * docs/x.ts) used to list only the destination, so the E2E Contract job (and
+ * every other src/-keyed flag) skipped a PR that removed a server input.
+ */
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { CHILD_PROCESS_TEST_BUDGET_MS, expectChildOk, runChild } from "./test-proc";
+
+type Workflow = {
+  jobs: Record<string, { steps: Array<{ id?: string; run?: string }> }>;
+};
+
+// The GitHub expression the step uses for the diff base; the test substitutes a local branch.
+const BASE_REF_EXPR = ["$", "{{ steps.base.outputs.ref }}"].join("");
+const WORKFLOW_PATH = join(import.meta.dir, "../../.github/workflows/merge-gate.yml");
+
+async function loadFlagStep(): Promise<string> {
+  const wf = Bun.YAML.parse(await Bun.file(WORKFLOW_PATH).text()) as Workflow;
+  const step = wf.jobs["detect-changes"]?.steps.find((s) => s.id === "check");
+  if (!step?.run) throw new Error("detect-changes step `check` not found in merge-gate.yml");
+  return step.run.replaceAll(BASE_REF_EXPR, "base");
+}
+
+// Isolate from the host's git config (a global diff.renames=false would make
+// the positive control pass for the wrong reason).
+const GIT_ENV = {
+  PATH: process.env.PATH,
+  HOME: tmpdir(),
+  GIT_CONFIG_NOSYSTEM: "1",
+  GIT_CONFIG_GLOBAL: "/dev/null",
+  GIT_AUTHOR_NAME: "t",
+  GIT_AUTHOR_EMAIL: "t@example.com",
+  GIT_COMMITTER_NAME: "t",
+  GIT_COMMITTER_EMAIL: "t@example.com",
+};
+
+const dirs: string[] = [];
+afterAll(async () => {
+  await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })));
+});
+
+async function git(cwd: string, ...args: string[]) {
+  return expectChildOk(await runChild(["git", ...args], { cwd, env: GIT_ENV }), `git ${args[0]}`);
+}
+
+// Large enough that git's default rename detection pairs the two sides.
+const BODY = Array.from({ length: 40 }, (_, i) => `export const v${i} = ${i};`).join("\n");
+
+/** Builds a repo whose `base` branch holds `files`, applies `change` on HEAD, and returns the step's flags. */
+async function flagsFor(
+  files: string[],
+  change: (repo: string) => Promise<void>,
+  script?: string,
+): Promise<Record<string, string>> {
+  const repo = await mkdtemp(join(tmpdir(), "merge-gate-flags-"));
+  dirs.push(repo);
+  await git(repo, "init", "-q", "-b", "base");
+  for (const f of files) {
+    await mkdir(dirname(join(repo, f)), { recursive: true });
+    await writeFile(join(repo, f), `${BODY}\n// ${f}\n`);
+  }
+  await git(repo, "add", "-A");
+  await git(repo, "commit", "-qm", "base");
+  await git(repo, "checkout", "-qb", "pr");
+  await change(repo);
+  await git(repo, "add", "-A");
+  await git(repo, "commit", "-qm", "pr");
+
+  const out = join(repo, ".gh-output");
+  const res = expectChildOk(
+    await runChild(["bash", "-c", script ?? (await loadFlagStep())], {
+      cwd: repo,
+      env: { ...GIT_ENV, GITHUB_OUTPUT: out },
+    }),
+    "flag step",
+  );
+  expect(res.stdout).toContain("Changed files:");
+  const flags: Record<string, string> = {};
+  for (const line of (await Bun.file(out).text()).split("\n")) {
+    const [k, v] = line.split("=");
+    if (k && v) flags[k] = v;
+  }
+  return flags;
+}
+
+const mv = (from: string, to: string) => async (repo: string) => {
+  await mkdir(dirname(join(repo, to)), { recursive: true });
+  await git(repo, "mv", from, to);
+};
+
+describe("merge-gate detect-changes flags", () => {
+  test(
+    "renaming a server file out of src/ still runs E2E",
+    async () => {
+      const flags = await flagsFor(["src/critical.ts"], mv("src/critical.ts", "docs/critical.ts"));
+      expect(flags.e2e).toBe("true");
+      expect(flags.test).toBe("true");
+      expect(flags.lint).toBe("true");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "renaming a docs file into src/ runs E2E",
+    async () => {
+      const flags = await flagsFor(["docs/notes.ts"], mv("docs/notes.ts", "src/notes.ts"));
+      expect(flags.e2e).toBe("true");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "a docs-only change skips E2E, tests, and lint",
+    async () => {
+      const flags = await flagsFor(["src/critical.ts", "docs/readme.md"], async (repo) => {
+        await writeFile(join(repo, "docs/readme.md"), "edited\n");
+      });
+      expect(flags.e2e).toBe("false");
+      expect(flags.test).toBe("false");
+      expect(flags.lint).toBe("false");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
+  test(
+    "control: with rename detection on, the outbound move hides from E2E",
+    async () => {
+      const step = await loadFlagStep();
+      expect(step).toContain("git diff --no-renames --name-only");
+      const flags = await flagsFor(
+        ["src/critical.ts"],
+        mv("src/critical.ts", "docs/critical.ts"),
+        step.replace("git diff --no-renames --name-only", "git diff --name-only"),
+      );
+      expect(flags.e2e).toBe("false");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+});