convex 1.34.0 → 1.34.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "convex",
   "description": "Client for the Convex Cloud",
-  "version": "1.34.0",
+  "version": "1.34.1",
   "author": "Convex, Inc. <no-reply@convex.dev>",
   "homepage": "https://convex.dev",
   "repository": {

package/schemas/convex.schema.json

@@ -189,9 +189,15 @@
       "type": "object",
       "description": "User-configurable settings for Convex AI files behavior.",
       "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "When false, disables all Convex AI files prompts and staleness messages in `npx convex dev`. Use `npx convex ai-files enable` to re-enable.",
+          "default": true
+        },
         "disableStalenessMessage": {
           "type": "boolean",
-          "description": "When true, suppresses Convex AI files install/staleness nags in `npx convex dev`.",
+          "description": "Deprecated. Use `enabled` instead.",
+          "deprecated": true,
           "default": false
         }
       },

package/src/browser/sync/authentication_manager.ts

@@ -174,6 +174,14 @@ export class AuthenticationManager {
       return;
     }
 
+    this._logVerbose(
+      `auth state is ${this.authState.state} when handling transition`,
+    );
+
+    // This transition advanced the auth version, which means the token used was valid
+    // and the client and server auth states are in sync.
+    this.syncState.markAuthCompletion();
+
     if (this.authState.state === "waitingForServerConfirmationOfCachedToken") {
       this._logVerbose("server confirmed auth token is valid");
       void this.refetchToken();
@@ -455,11 +463,8 @@ export class AuthenticationManager {
       }
     }
     if (this.authState.state === "waitingForScheduledRefetch") {
+      // TODO: this side-effect would be better situated with scheduling refetch
       clearTimeout(this.authState.refetchTokenTimeoutId);
-
-      // The waitingForScheduledRefetch state is the most quiesced authed state.
-      // Let the syncState know that auth is in a good state, so it can reset failure backoffs
-      this.syncState.markAuthCompletion();
     }
     this.authState = newAuth;
   }

package/src/browser/sync/client_node.test.ts

@@ -2,6 +2,7 @@ import child_process from "child_process";
 
 import { test, expect } from "vitest";
 import { Long } from "../../vendor/long.js";
+import { createHmac } from "crypto";
 
 import { BaseConvexClient } from "./client.js";
 import {
@@ -1026,3 +1027,127 @@ test("Backoff does not reset for idle client until server re-confirms queries",
     await client.close();
   });
 });
+
+// We had an issue where fixing a bug related to having the client do proper exponential backoff
+// resulted in revealing that if a client was authenticated and had a WebSocket disconnect, the
+// count of retries would never get reset upon reconnect. This test covers that scenario.
+test("Retries do not increase across connections for auth'd clients", async () => {
+  await withInMemoryWebSocket(async ({ address, receive, send, close }) => {
+    const client = new BaseConvexClient(address, () => null, {
+      webSocketConstructor: nodeWebSocket,
+      unsavedChangesWarning: false,
+      logger: true,
+      verbose: true,
+    });
+
+    // Setup auth
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = iat + 3600;
+    const token = encodeJwt({ sub: "user_123", exp, iat }, "test-secret");
+    client.setAuth(
+      async () => token,
+      (_) => {},
+    );
+
+    // Verify client handshake on "server" side.
+    expect((await receive()).type).toEqual("Connect");
+    expect((await receive()).type).toEqual("Authenticate");
+    expect((await receive()).type).toEqual("ModifyQuerySet");
+
+    // Respond to the handshake noting that the identity was accepted (increased version).
+    send({
+      type: "Transition",
+      startVersion: { querySet: 0, identity: 0, ts: Long.fromNumber(0) },
+      endVersion: { querySet: 0, identity: 1, ts: Long.fromNumber(100) },
+      modifications: [],
+    });
+
+    // Subscribe to a query and verify the "server" receives it.
+    client.subscribe("queries:myQuery", {});
+    expect((await receive()).type).toEqual("ModifyQuerySet");
+
+    // Respond to the subscription with a result.
+    send({
+      type: "Transition",
+      startVersion: { querySet: 0, identity: 1, ts: Long.fromNumber(100) },
+      endVersion: { querySet: 1, identity: 1, ts: Long.fromNumber(200) },
+      modifications: [
+        {
+          type: "QueryUpdated",
+          queryId: 0,
+          value: "result",
+          logLines: [],
+          journal: null,
+        },
+      ],
+    });
+
+    // Verify the client gets the subscription result.
+    for (let i = 0; i < 20; i++) {
+      if (client.localQueryResult("queries:myQuery", {}) === "result") break;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    expect(client.localQueryResult("queries:myQuery", {})).toEqual("result");
+
+    // Unceremoniously drop the connection.
+    close();
+
+    // The "server" should see the client handshake for a reconnect.
+    expect((await receive()).type).toEqual("Connect");
+    expect((await receive()).type).toEqual("Authenticate");
+    expect((await receive()).type).toEqual("ModifyQuerySet");
+
+    // The client should record that it has begun a retry.
+    expect(client.connectionState().connectionRetries).toBe(1);
+
+    // Respond to the handshake noting that the identity was accepted (increased version).
+    send({
+      type: "Transition",
+      startVersion: { querySet: 0, identity: 0, ts: Long.fromNumber(0) },
+      endVersion: { querySet: 0, identity: 1, ts: Long.fromNumber(100) },
+      modifications: [],
+    });
+    // Let client handle the transition.
+    await new Promise((r) => setTimeout(r, 100));
+
+    // Respond to the re-subscription with a result.
+    send({
+      type: "Transition",
+      startVersion: { querySet: 0, identity: 1, ts: Long.fromNumber(100) },
+      endVersion: { querySet: 1, identity: 1, ts: Long.fromNumber(200) },
+      modifications: [
+        {
+          type: "QueryUpdated",
+          queryId: 0,
+          value: "updated result",
+          logLines: [],
+          journal: null,
+        },
+      ],
+    });
+
+    for (let i = 0; i < 20; i++) {
+      if (client.localQueryResult("queries:myQuery", {}) === "updated result")
+        break;
+      await new Promise((r) => setTimeout(r, 50));
+    }
+    // Verify the client gets the subscription result.
+    expect(client.localQueryResult("queries:myQuery", {})).toEqual(
+      "updated result",
+    );
+
+    // Client has resynced - should be at 0 retries
+    expect(client.connectionState().connectionRetries).toBe(0);
+  });
+});
+
+function encodeJwt(payload: object, secret: string): string {
+  const header = Buffer.from(
+    JSON.stringify({ alg: "HS256", typ: "JWT" }),
+  ).toString("base64url");
+  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const sig = createHmac("sha256", secret)
+    .update(`${header}.${body}`)
+    .digest("base64url");
+  return `${header}.${body}.${sig}`;
+}

package/src/browser/sync/web_socket_manager.ts

@@ -126,12 +126,6 @@ const serverDisconnectErrors = {
   VectorIndexesUnavailable: { timeout: 1000 },
   SearchIndexesUnavailable: { timeout: 1000 },
   TableSummariesUnavailable: { timeout: 1000 },
-  // ErrorMetadata::service_unavailable() when backend/conductor is unreachable
-  ServiceUnavailable: { timeout: 3000 },
-  // ErrorMetadata::rejected_before_execution() when funrun workers are unavailable
-  WorkerOverloaded: { timeout: 3000 },
-  IsolateNotClean: { timeout: 3000 },
-  InitialPermitTimeoutError: { timeout: 3000 },
   // More ErrorMetadata::overloaded()
   VectorIndexTooLarge: { timeout: 3000 },
   SearchIndexTooLarge: { timeout: 3000 },
@@ -235,7 +229,7 @@ export class WebSocketManager {
 
     // backoff for unknown errors
     this.defaultInitialBackoff = 1000;
-    this.maxBackoff = 64000;
+    this.maxBackoff = 16000;
     this.retries = 0;
 
     // Ping messages (sync protocol Pings, not WebSocket protocol Pings) are

package/src/cli/aiFiles.ts

@@ -4,12 +4,12 @@ import { oneoffContext } from "../bundler/context.js";
 import { readProjectConfig } from "./lib/config.js";
 import { functionsDir } from "./lib/utils/utils.js";
 import {
-  updateAiFiles,
+  installAiFiles,
   enableAiFiles,
   removeAiFiles,
-  disableAiFiles,
-  statusAiFiles,
-} from "./lib/ai/index.js";
+  safelyAttemptToDisableAiFiles,
+} from "./lib/aiFiles/index.js";
+import { statusAiFiles } from "./lib/aiFiles/status.js";
 
 async function resolveProjectPaths() {
   const ctx = await oneoffContext({});
@@ -26,53 +26,46 @@ const aiInstall = new Command("install")
       "  - convex/_generated/ai/guidelines.md\n" +
       "  - AGENTS.md (Convex section only)\n" +
       "  - CLAUDE.md (Convex section only)\n" +
-      "  - Agent skills (installed to each coding agent's native path)\n\n" +
-      "Files you have edited yourself are detected via content hashing and skipped\n" +
-      "rather than silently overwritten.",
+      "  - Agent skills (installed to each coding agent's native path)",
   )
   .allowExcessArguments(false)
   .action(async () => {
     const { projectDir, convexDir } = await resolveProjectPaths();
-    await updateAiFiles(projectDir, convexDir);
+    await installAiFiles({ projectDir, convexDir });
   });
 
 const aiEnable = new Command("enable")
-  .summary("Enable Convex AI file staleness/install messages")
+  .summary("Enable Convex AI files")
   .description(
-    "Re-enables AI file staleness/install messages by writing\n" +
-      "`aiFiles.disableStalenessMessage: false` to `convex.json`, then installs\n" +
-      "or refreshes the managed AI files.",
+    "Re-enables Convex AI files by writing `aiFiles.enabled: true` to\n" +
+      "`convex.json`, then installs or refreshes the managed AI files.",
   )
   .allowExcessArguments(false)
   .action(async () => {
     const { projectDir, convexDir } = await resolveProjectPaths();
-    await enableAiFiles(projectDir, convexDir);
+    await enableAiFiles({ projectDir, convexDir });
   });
 
 const aiUpdate = new Command("update")
   .summary("Update Convex AI files to the latest version")
   .description(
-    "Updates the following files if they exist and have not been locally modified:\n" +
+    "Updates the following to their latest versions:\n" +
       "  - convex/_generated/ai/guidelines.md\n" +
       "  - AGENTS.md (Convex section only)\n" +
       "  - CLAUDE.md (Convex section only)\n" +
-      "  - Agent skills (installed to each coding agent's native path)\n\n" +
-      "Files you have edited yourself are detected via content hashing and skipped\n" +
-      "rather than silently overwritten.\n\n" +
-      "Does not change `aiFiles.disableStalenessMessage` in `convex.json`.\n" +
-      "Run `npx convex ai-files enable` to enable staleness/install messages.",
+      "  - Agent skills (installed to each coding agent's native path)\n\n",
   )
   .allowExcessArguments(false)
   .action(async () => {
     const { projectDir, convexDir } = await resolveProjectPaths();
-    await updateAiFiles(projectDir, convexDir);
+    await installAiFiles({ projectDir, convexDir });
   });
 
 const aiDisable = new Command("disable")
-  .summary("Suppress AI file staleness/install messages without removing files")
+  .summary("Disable Convex AI files without removing them")
   .description(
-    "Writes a suppression marker into `convex.json` (`aiFiles.disableStalenessMessage`) so\n" +
-      "`npx convex dev` stops suggesting you install AI files.\n\n" +
+    "Writes `aiFiles.enabled: false` to `convex.json` so `npx convex dev`\n" +
+      "stops prompting to install AI files and suppresses staleness messages.\n\n" +
       "Files already installed are left untouched - use `npx convex ai-files remove`\n" +
       "if you also want to delete them.\n\n" +
       "Run `npx convex ai-files enable` to re-enable at any time.",
@@ -80,7 +73,7 @@ const aiDisable = new Command("disable")
   .allowExcessArguments(false)
   .action(async () => {
     const { projectDir } = await resolveProjectPaths();
-    await disableAiFiles(projectDir);
+    await safelyAttemptToDisableAiFiles(projectDir);
   });
 
 const aiStatus = new Command("status")
@@ -98,7 +91,7 @@ const aiStatus = new Command("status")
   .allowExcessArguments(false)
   .action(async () => {
     const { projectDir, convexDir } = await resolveProjectPaths();
-    await statusAiFiles(projectDir, convexDir);
+    await statusAiFiles({ projectDir, convexDir });
   });
 
 const aiRemove = new Command("remove")
@@ -112,12 +105,12 @@ const aiRemove = new Command("remove")
       "empty file is deleted. Otherwise the rest of the file is kept.\n\n" +
       "Skills installed from other sources are not affected.\n\n" +
       "Note: after `remove`, `npx convex dev` will suggest reinstalling AI files.\n" +
-      "Use `npx convex ai-files disable` to suppress that prompt without deleting files.",
+      "Use `npx convex ai-files disable` to opt out entirely without deleting files.",
   )
   .allowExcessArguments(false)
   .action(async () => {
     const { projectDir, convexDir } = await resolveProjectPaths();
-    await removeAiFiles(projectDir, convexDir);
+    await removeAiFiles({ projectDir, convexDir });
   });
 
 export const aiFiles = new Command("ai-files")

package/src/cli/configure.ts

@@ -44,7 +44,7 @@ import {
   promptYesNo,
 } from "./lib/utils/prompts.js";
 import { readGlobalConfig } from "./lib/utils/globalConfig.js";
-import { maybeSetupAiFiles } from "./lib/ai/index.js";
+import { maybeSetupAiFiles } from "./lib/aiFiles/index.js";
 import {
   DeploymentSelection,
   deploymentNameFromSelection,
@@ -382,14 +382,20 @@ async function handleDeploymentWithinProject(
     selectedDeployment.deploymentFields !== null &&
     selectedDeployment.deploymentFields.deploymentType === "local"
   ) {
-    // Start running the local backend
-    await handleLocalDeployment(ctx, {
+    // Start running the local backend, which may bind to different ports
+    // than what was saved from a previous run.
+    const localDeployment = await handleLocalDeployment(ctx, {
       teamSlug: selectedDeployment.deploymentFields.teamSlug!,
       projectSlug: selectedDeployment.deploymentFields.projectSlug!,
       forceUpgrade: cmdOptions.localOptions.forceUpgrade,
       ports: cmdOptions.localOptions.ports,
       backendVersion: cmdOptions.localOptions.backendVersion,
     });
+    return {
+      url: localDeployment.deploymentUrl,
+      adminKey: localDeployment.adminKey,
+      deploymentFields: selectedDeployment.deploymentFields,
+    };
   }
   return {
     url: selectedDeployment.url,
@@ -619,11 +625,11 @@ async function selectNewProject(
   await doInitConvexFolder(ctx);
   const { configPath, projectConfig } = await readProjectConfig(ctx);
   const folder = functionsDir(configPath, projectConfig);
-  await maybeSetupAiFiles(
+  await maybeSetupAiFiles({
     ctx,
-    path.resolve(folder),
-    path.resolve(path.dirname(configPath)),
-  );
+    convexDir: path.resolve(folder),
+    projectDir: path.resolve(path.dirname(configPath)),
+  });
   return { teamSlug, projectSlug, devDeployment };
 }
 
@@ -679,11 +685,11 @@ async function selectExistingProject(
 
   const { configPath, projectConfig } = await readProjectConfig(ctx);
   const folder = functionsDir(configPath, projectConfig);
-  await maybeSetupAiFiles(
+  await maybeSetupAiFiles({
     ctx,
-    path.resolve(folder),
-    path.resolve(path.dirname(configPath)),
-  );
+    convexDir: path.resolve(folder),
+    projectDir: path.resolve(path.dirname(configPath)),
+  });
 
   return { teamSlug, projectSlug, devDeployment };
 }

package/src/cli/deploymentSelection.test.ts

@@ -161,8 +161,9 @@ vi.mock("./lib/login.js", async (importOriginal) => {
   return { ...actual, ensureLoggedIn: vi.fn() };
 });
 
-vi.mock("./lib/ai/index.js", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("./lib/ai/index.js")>();
+vi.mock("./lib/aiFiles/index.js", async (importOriginal) => {
+  const actual =
+    await importOriginal<typeof import("./lib/aiFiles/index.js")>();
   return { ...actual, maybeSetupAiFiles: vi.fn() };
 });
 
@@ -1555,6 +1556,59 @@ describe("deployment selection flows", () => {
       expect(bigBrainAPIMaybeThrows).not.toHaveBeenCalled();
     });
 
+    it("dev with CONVEX_DEPLOYMENT=local:... uses fresh credentials from handleLocalDeployment", async () => {
+      process.env.CONVEX_DEPLOYMENT = "local:my-local-deployment";
+      vi.mocked(readGlobalConfig).mockReturnValue({
+        accessToken: "test-token",
+      });
+
+      // loadLocalDeploymentCredentials returns stale saved config (e.g. from a
+      // previous run on a different port).
+      vi.mocked(loadLocalDeploymentCredentials).mockResolvedValue({
+        deploymentName: "my-local-deployment",
+        deploymentUrl: "http://127.0.0.1:3212",
+        adminKey: "stale|admin|key",
+      });
+
+      // handleLocalDeployment starts a new backend, potentially on different
+      // ports, and returns the actual credentials.
+      vi.mocked(handleLocalDeployment).mockResolvedValue({
+        deploymentName: "my-local-deployment",
+        deploymentUrl: "http://127.0.0.1:3210",
+        adminKey: "fresh|admin|key",
+        onActivity: async () => {},
+      } as any);
+
+      setupBigBrainRoutes({
+        "deployment/my-local-deployment/team_and_project": () => ({
+          team: "my-team",
+          project: "my-project",
+          teamId: 1,
+          projectId: 1,
+        }),
+      });
+
+      await dev.parseAsync([], { from: "user" });
+
+      expect(handleLocalDeployment).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({
+          teamSlug: "my-team",
+          projectSlug: "my-project",
+        }),
+      );
+      // Must use the fresh credentials from handleLocalDeployment, not the
+      // stale ones from loadLocalDeploymentCredentials.
+      expect(devAgainstDeployment).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({
+          url: "http://127.0.0.1:3210",
+          adminKey: "fresh|admin|key",
+        }),
+        expect.anything(),
+      );
+    });
+
     it("dev --local crashes when local deployments are globally disabled", async () => {
       vi.mocked(readGlobalConfig).mockReturnValue({
         accessToken: "test-token",

package/src/cli/lib/{ai → aiFiles}/MANUAL_TESTING.md

@@ -27,8 +27,12 @@ After `npx convex ai-files install` (or `update`) verify:
 - `.cursor/skills/` (Cursor symlinks)
 - `.claude/skills/` (Claude Code symlinks)
 
-Expected skill set: `auth-setup`, `components-guide`, `convex-helpers-guide`,
-`convex-quickstart`, `function-creator`, `migration-helper`, `schema-builder`.
+Expected skill set (as of Mar 2026): `convex-create-component`,
+`convex-migration-helper`, `convex-performance-audit`, `convex-quickstart`,
+`convex-setup-auth`.
+
+Note: the live skill set is fetched remotely and may change. Check the current
+list against what `npx convex ai-files status` reports after install.
 
 **Why manual:** these paths and symlink behaviors are environment-dependent and
 are mocked in automated tests.

package/src/cli/lib/aiFiles/agentsmd.test.ts

@@ -0,0 +1,133 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { injectAgentsMdSection, hasAgentsMdInstalled } from "./agentsmd.js";
+import {
+  AGENTS_MD_START_MARKER,
+  AGENTS_MD_END_MARKER,
+} from "../../codegen_templates/agentsmd.js";
+
+describe("injectAgentsMdSection", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const section = `${AGENTS_MD_START_MARKER}\n## Convex\nRead guidelines.\n${AGENTS_MD_END_MARKER}`;
+
+  test("creates AGENTS.md when it does not exist", async () => {
+    await injectAgentsMdSection({ section, projectDir: tmpDir });
+
+    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
+    expect(content).toContain(AGENTS_MD_START_MARKER);
+    expect(content).toContain(AGENTS_MD_END_MARKER);
+    expect(content).toContain("## Convex");
+  });
+
+  test("appends to an existing AGENTS.md that has no Convex section", async () => {
+    const existing = "# My project\n\nSome existing content.\n";
+    fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), existing);
+
+    await injectAgentsMdSection({ section, projectDir: tmpDir });
+
+    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
+    expect(content).toContain("# My project");
+    expect(content).toContain("Some existing content.");
+    expect(content).toContain(AGENTS_MD_START_MARKER);
+    expect(content).toContain("## Convex");
+  });
+
+  test("replaces an existing Convex section when markers are present", async () => {
+    const oldSection = `${AGENTS_MD_START_MARKER}\n## Convex\nOld content.\n${AGENTS_MD_END_MARKER}`;
+    const existing = `# My project\n\n${oldSection}\n`;
+    fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), existing);
+
+    const newSection = `${AGENTS_MD_START_MARKER}\n## Convex\nNew content.\n${AGENTS_MD_END_MARKER}`;
+    await injectAgentsMdSection({ section: newSection, projectDir: tmpDir });
+
+    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
+    expect(content).toContain("New content.");
+    expect(content).not.toContain("Old content.");
+    expect(content.split(AGENTS_MD_START_MARKER).length - 1).toBe(1);
+  });
+
+  test("preserves content before and after an existing Convex section", async () => {
+    const oldSection = `${AGENTS_MD_START_MARKER}\n## Convex\nOld.\n${AGENTS_MD_END_MARKER}`;
+    const existing = `# Before\n\n${oldSection}\n\n# After\n`;
+    fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), existing);
+
+    await injectAgentsMdSection({ section, projectDir: tmpDir });
+
+    const content = fs.readFileSync(path.join(tmpDir, "AGENTS.md"), "utf8");
+    expect(content).toContain("# Before");
+    expect(content).toContain("# After");
+  });
+
+  test("returns a non-null hash of the written content", async () => {
+    const result = await injectAgentsMdSection({ section, projectDir: tmpDir });
+    expect(typeof result.sectionHash).toBe("string");
+    expect(result.sectionHash.length).toBeGreaterThan(0);
+    expect(result.didWrite).toBe(true);
+  });
+
+  test("returns hash of the section content, not the entire file", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "AGENTS.md"),
+      "# My project\n\nExisting content.\n",
+    );
+
+    const result = await injectAgentsMdSection({ section, projectDir: tmpDir });
+
+    const { hashSha256 } = await import("../utils/hash.js");
+    expect(result.sectionHash).toBe(hashSha256(section));
+  });
+
+  test("does not write when content is unchanged", async () => {
+    await injectAgentsMdSection({ section, projectDir: tmpDir });
+    const result = await injectAgentsMdSection({ section, projectDir: tmpDir });
+    expect(result.didWrite).toBe(false);
+  });
+});
+
+describe("hasAgentsMdInstalled", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(`${os.tmpdir()}${path.sep}`);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("returns false when AGENTS.md does not exist", async () => {
+    expect(await hasAgentsMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns false when AGENTS.md exists but has no managed markers", async () => {
+    fs.writeFileSync(path.join(tmpDir, "AGENTS.md"), "User content only\n");
+    expect(await hasAgentsMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns false when only the start marker is present", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "AGENTS.md"),
+      `${AGENTS_MD_START_MARKER}\npartial content\n`,
+    );
+    expect(await hasAgentsMdInstalled(tmpDir)).toBe(false);
+  });
+
+  test("returns true when both markers are present", async () => {
+    fs.writeFileSync(
+      path.join(tmpDir, "AGENTS.md"),
+      `# Project\n\n${AGENTS_MD_START_MARKER}\n## Convex\n${AGENTS_MD_END_MARKER}\n`,
+    );
+    expect(await hasAgentsMdInstalled(tmpDir)).toBe(true);
+  });
+});