@mycadet/cli 0.12.7 → 0.12.9

package/src/__tests__/{recover.test.ts → restore.test.ts}

@@ -61,7 +61,7 @@ afterAll(() => {
   mock.module("../lib/step-runner.js", () => ({ exec: realExec }));
 });
 
-import { recover } from "../commands/recover.js";
+import { restore } from "../commands/restore.js";
 
 // ── Test fixtures ─────────────────────────────────────────────────────────────
 
@@ -175,18 +175,19 @@ afterAll(() => {
 
 // ── Tests ─────────────────────────────────────────────────────────────────────
 
-describe("recover --help", () => {
+describe("restore --help", () => {
   test("prints usage, description, and examples then exits 0", async () => {
-    process.argv = ["bun", "cadet", "recover", "--help"];
-    await expect(recover()).rejects.toThrow("process.exit(0)");
+    process.argv = ["bun", "cadet", "restore", "--help"];
+    await expect(restore()).rejects.toThrow("process.exit(0)");
     const output = consoleLogSpy.mock.calls.flat().join("\n");
-    expect(output).toContain("Usage: cadet recover <name>");
+    expect(output).toContain("Usage: cadet restore <name>");
+    expect(output).toContain("recovers a retired assistant");
     expect(output).toContain("Examples:");
-    expect(output).toContain("cadet recover");
+    expect(output).toContain("cadet restore");
   });
 });
 
-describe("recover error cases", () => {
+describe("restore error cases", () => {
   for (const failure of ["missing", "conflict"] as const) {
     test(`recovery ${failure} leaves destination and registry untouched and permits retry`, async () => {
       const name = `retry-${failure}`;
@@ -211,8 +212,8 @@ describe("recover error cases", () => {
       }
       const registry = resolveLockfilePaths(process.env)[0]!;
       const before = readFileSync(registry, "utf8");
-      process.argv = ["bun", "cadet", "recover", name];
-      await expect(recover()).rejects.toThrow(`signing key ${failure}`);
+      process.argv = ["bun", "cadet", "restore", name];
+      await expect(restore()).rejects.toThrow(`signing key ${failure}`);
       expect(existsSync(instanceDir)).toBe(false);
       expect(readFileSync(registry, "utf8")).toBe(before);
       expect(existsSync(archivePath)).toBe(true);
@@ -222,7 +223,7 @@ describe("recover error cases", () => {
       // Restore the authoritative identity in the archive metadata and retry.
       entry.resources!.signingKey = "ab".repeat(32);
       writeFileSync(metadataPath, JSON.stringify(entry));
-      await recover();
+      await restore();
       expect(existsSync(instanceDir)).toBe(true);
       expect(existsSync(archivePath)).toBe(false);
       expect(startGatewayMock).toHaveBeenCalledTimes(1);
@@ -241,8 +242,8 @@ describe("recover error cases", () => {
       join(dir, "actor-token-signing-key"),
       Buffer.from("cd".repeat(32), "hex"),
     );
-    process.argv = ["bun", "cadet", "recover", name];
-    await recover();
+    process.argv = ["bun", "cadet", "restore", name];
+    await restore();
     expect(startGatewayMock).toHaveBeenCalledWith(
       false,
       expect.objectContaining({ signingKey: "cd".repeat(32) }),
@@ -256,8 +257,8 @@ describe("recover error cases", () => {
     const entry = makeEntry(name, join(testDir, "cadet", "assistants", name));
     delete entry.resources!.signingKey;
     const { archivePath, metadataPath } = writeArchiveFixtures(name, entry);
-    process.argv = ["bun", "cadet", "recover", name];
-    await expect(recover()).rejects.toThrow("signing key missing");
+    process.argv = ["bun", "cadet", "restore", name];
+    await expect(restore()).rejects.toThrow("signing key missing");
     expect(existsSync(archivePath)).toBe(true);
     expect(existsSync(metadataPath)).toBe(true);
     expect(startLocalDaemonMock).not.toHaveBeenCalled();
@@ -265,14 +266,14 @@ describe("recover error cases", () => {
   });
 
   test("exits 1 when no name is given", async () => {
-    process.argv = ["bun", "cadet", "recover"];
-    await expect(recover()).rejects.toThrow("process.exit(1)");
-    expect(consoleErrorSpy.mock.calls[0][0]).toContain("Usage:");
+    process.argv = ["bun", "cadet", "restore"];
+    await expect(restore()).rejects.toThrow("process.exit(1)");
+    expect(consoleErrorSpy.mock.calls[0][0]).toContain("<name> is required");
   });
 
   test("exits 1 when archive is missing", async () => {
-    process.argv = ["bun", "cadet", "recover", "ghost-assistant"];
-    await expect(recover()).rejects.toThrow("process.exit(1)");
+    process.argv = ["bun", "cadet", "restore", "ghost-assistant"];
+    await expect(restore()).rejects.toThrow("process.exit(1)");
     expect(consoleErrorSpy.mock.calls[0][0]).toContain(
       "No retired archive found for 'ghost-assistant'",
     );
@@ -292,8 +293,8 @@ describe("recover error cases", () => {
       join(retiredDir, `${name}.json`),
       JSON.stringify(entry, null, 2) + "\n",
     );
-    process.argv = ["bun", "cadet", "recover", name];
-    await expect(recover()).rejects.toThrow("missing resource configuration");
+    process.argv = ["bun", "cadet", "restore", name];
+    await expect(restore()).rejects.toThrow("missing resource configuration");
   });
 
   test("exits 1 when target .cadet/ already exists", async () => {
@@ -303,13 +304,13 @@ describe("recover error cases", () => {
     writeArchiveFixtures(name, entry);
     // Pre-create the collision path that recover checks
     mkdirSync(join(instanceDir, ".cadet"), { recursive: true });
-    process.argv = ["bun", "cadet", "recover", name];
-    await expect(recover()).rejects.toThrow("process.exit(1)");
+    process.argv = ["bun", "cadet", "restore", name];
+    await expect(restore()).rejects.toThrow("process.exit(1)");
     expect(consoleErrorSpy.mock.calls[0][0]).toContain("already exists");
   });
 });
 
-describe("recover extraction path — named instance (instanceDir !== homedir())", () => {
+describe("archive-recovery extraction path — named instance (instanceDir !== homedir())", () => {
   test("extracts to retiredDir and renames staging dir to instanceDir directly", async () => {
     const name = "named-instance";
     const instanceDir = join(testDir, "custom-location", name);
@@ -321,8 +322,8 @@ describe("recover extraction path — named instance (instanceDir !== homedir())
     // Parent dir must exist for renameSync
     mkdirSync(join(testDir, "custom-location"), { recursive: true });
 
-    process.argv = ["bun", "cadet", "recover", name];
-    await recover();
+    process.argv = ["bun", "cadet", "restore", name];
+    await restore();
 
     // exec must have been called with -C retiredDir
     expect(execMock).toHaveBeenCalledTimes(1);
@@ -355,8 +356,8 @@ describe("recover extraction path — named instance (instanceDir !== homedir())
     const entry = makeEntry(name, instanceDir);
     const { archivePath, extractedPath } = writeArchiveFixtures(name, entry);
 
-    process.argv = ["bun", "cadet", "recover", name];
-    await recover();
+    process.argv = ["bun", "cadet", "restore", name];
+    await restore();
 
     expect(existsSync(extractedPath)).toBe(false);
     expect(existsSync(instanceDir)).toBe(true);

package/src/__tests__/retire.test.ts

@@ -21,7 +21,7 @@ import { join } from "node:path";
 import type { AssistantEntry } from "../lib/assistant-config.js";
 import { loadAllAssistants } from "../lib/assistant-config.js";
 import * as loopbackFetchModule from "../lib/loopback-fetch.js";
-import * as platformClientModule from "../lib/platform-client.js";
+import * as cloudClientModule from "../lib/cloud-client.js";
 import * as retireLocalModule from "../lib/retire-local.js";
 
 const testDir = mkdtempSync(join(tmpdir(), "cli-retire-test-"));
@@ -35,11 +35,11 @@ const originalStdinIsRaw = process.stdin.isRaw;
 const originalSetRawMode = process.stdin.setRawMode;
 const originalStdoutWrite = process.stdout.write;
 const realRetireLocalModule = { ...retireLocalModule };
-const realPlatformClientModule = { ...platformClientModule };
+const realCloudClientModule = { ...cloudClientModule };
 const realLoopbackFetchModule = { ...loopbackFetchModule };
 
 const retireLocalMock = mock(async () => {});
-const readPlatformTokenMock = mock((): string | null => null);
+const readCloudTokenMock = mock((): string | null => null);
 const authHeadersMock = mock(async () => ({
   "Content-Type": "application/json",
   "X-Session-Token": "session-token",
@@ -51,7 +51,7 @@ const authHeadersForKnownOrganizationMock = mock(
     "Cadet-Organization-Id": organizationId,
   }),
 );
-const getPlatformUrlMock = mock(() => "https://platform.example.com");
+const getCloudUrlMock = mock(() => "https://platform.example.com");
 const readGatewayCredentialMock = mock(
   async (
     _gatewayUrl: string,
@@ -71,12 +71,12 @@ mock.module("../lib/retire-local.js", () => ({
   retireLocal: retireLocalMock,
 }));
 
-mock.module("../lib/platform-client.js", () => ({
+mock.module("../lib/cloud-client.js", () => ({
   authHeaders: authHeadersMock,
   authHeadersForKnownOrganization: authHeadersForKnownOrganizationMock,
-  getPlatformUrl: getPlatformUrlMock,
+  getCloudUrl: getCloudUrlMock,
   readGatewayCredential: readGatewayCredentialMock,
-  readPlatformToken: readPlatformTokenMock,
+  readCloudToken: readCloudTokenMock,
 }));
 
 mock.module("../lib/loopback-fetch.js", () => ({
@@ -168,7 +168,11 @@ describe("cadet retire", () => {
   beforeEach(() => {
     process.env.CADET_LOCKFILE_DIR = testDir;
     delete process.env.CADET_PLATFORM_TOKEN;
-    for (const name of ["lockfile.json", ".cadet.lock.json", ".cadet.lockfile.json"]) {
+    for (const name of [
+      "lockfile.json",
+      ".cadet.lock.json",
+      ".cadet.lockfile.json",
+    ]) {
       rmSync(join(testDir, name), { force: true });
     }
     process.argv = ["bun", "cadet", "retire"];
@@ -177,8 +181,8 @@ describe("cadet retire", () => {
     }) as typeof process.exit;
     retireLocalMock.mockReset();
     retireLocalMock.mockResolvedValue(undefined);
-    readPlatformTokenMock.mockReset();
-    readPlatformTokenMock.mockReturnValue(null);
+    readCloudTokenMock.mockReset();
+    readCloudTokenMock.mockReturnValue(null);
     authHeadersMock.mockReset();
     authHeadersMock.mockResolvedValue({
       "Content-Type": "application/json",
@@ -192,8 +196,8 @@ describe("cadet retire", () => {
         "Cadet-Organization-Id": organizationId,
       }),
     );
-    getPlatformUrlMock.mockReset();
-    getPlatformUrlMock.mockReturnValue("https://platform.example.com");
+    getCloudUrlMock.mockReset();
+    getCloudUrlMock.mockReturnValue("https://platform.example.com");
     readGatewayCredentialMock.mockReset();
     readGatewayCredentialMock.mockResolvedValue({
       value: null,
@@ -220,7 +224,7 @@ describe("cadet retire", () => {
 
   afterAll(() => {
     mock.module("../lib/retire-local.js", () => realRetireLocalModule);
-    mock.module("../lib/platform-client.js", () => realPlatformClientModule);
+    mock.module("../lib/cloud-client.js", () => realCloudClientModule);
     mock.module("../lib/loopback-fetch.js", () => realLoopbackFetchModule);
     if (originalLockfileDir === undefined) {
       delete process.env.CADET_LOCKFILE_DIR;
@@ -252,35 +256,25 @@ describe("cadet retire", () => {
     );
   });
 
-  test("local retire unregisters the self-hosted platform record first", async () => {
-    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
-    writeLockfile([entry]);
-    readPlatformTokenMock.mockReturnValue("session-token");
-    getPlatformUrlMock.mockReturnValue("https://platform.example.test/api");
-    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
-      if (name === "cadet:platform_assistant_id") {
-        return { value: "platform-assistant-1", unreachable: false };
-      }
-      if (name === "cadet:platform_base_url") {
-        return { value: "https://platform.example.test", unreachable: false };
-      }
-      if (name === "cadet:platform_organization_id") {
-        return { value: "org-123", unreachable: false };
-      }
-      return { value: null, unreachable: false };
+  test("local retire unregisters the cloud record straight from the lockfile entry", async () => {
+    const entry = makeEntry("assistant-1", {
+      name: "Example Assistant",
+      localUrl: "http://127.0.0.1:7831",
+      cloudAssistantId: "cloud-asst-1",
+      cloudOrganizationId: "org-123",
     });
+    writeLockfile([entry]);
+    readCloudTokenMock.mockReturnValue("session-token");
+    getCloudUrlMock.mockReturnValue("https://platform.example.test");
     process.argv = ["bun", "cadet", "retire", "assistant-1", "--yes"];
 
     await retire();
 
-    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
-      entry.localUrl ?? entry.runtimeUrl,
-      "cadet:platform_assistant_id",
-      entry.bearerToken,
-    );
-    expect(authHeadersMock).not.toHaveBeenCalled();
+    // The cloud record resolves from the entry + env — the local gateway
+    // credential store is never consulted.
+    expect(readGatewayCredentialMock).not.toHaveBeenCalled();
     expect(loopbackSafeFetchMock).toHaveBeenCalledWith(
-      "https://platform.example.test/api/v1/assistants/platform-assistant-1/retire/",
+      "https://platform.example.test/v1/assistants/cloud-asst-1/retire/",
       {
         method: "DELETE",
         headers: {
@@ -294,194 +288,67 @@ describe("cadet retire", () => {
     expect(loadAllAssistants()).toEqual([]);
   });
 
-  test("local retire reads platform registration through the loopback gateway URL", async () => {
-    const localGatewayUrl = "http://127.0.0.1:7831";
-    const entry = makeEntry("assistant-1", {
-      name: "Example Assistant",
-      runtimeUrl: "http://assistant-1.local:7831",
-      localUrl: localGatewayUrl,
-    });
-    writeLockfile([entry]);
-    readPlatformTokenMock.mockReturnValue("session-token");
-    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
-    readGatewayCredentialMock.mockImplementation(async (gatewayUrl, name) => {
-      expect(gatewayUrl).toBe(localGatewayUrl);
-      if (name === "cadet:platform_assistant_id") {
-        return { value: "platform-assistant-1", unreachable: false };
-      }
-      if (name === "cadet:platform_base_url") {
-        return { value: "https://platform.example.test", unreachable: false };
-      }
-      if (name === "cadet:platform_organization_id") {
-        return { value: "org-123", unreachable: false };
-      }
-      return { value: null, unreachable: false };
-    });
-    process.argv = ["bun", "cadet", "retire", "assistant-1", "--yes"];
-
-    await retire();
-
-    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
-      localGatewayUrl,
-      "cadet:platform_assistant_id",
-      entry.bearerToken,
-    );
-    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
-      localGatewayUrl,
-      "cadet:platform_base_url",
-      entry.bearerToken,
-    );
-    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
-      localGatewayUrl,
-      "cadet:platform_organization_id",
-      entry.bearerToken,
-    );
-    expect(loopbackSafeFetchMock).toHaveBeenCalledWith(
-      "https://platform.example.test/v1/assistants/platform-assistant-1/retire/",
-      expect.any(Object),
-    );
-    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
-  });
-
-  test("local retire uses saved platform registration when local credentials are unreachable", async () => {
+  test("local retire resolves the organization via the cloud when the entry omits it", async () => {
     const entry = makeEntry("assistant-1", {
       name: "Example Assistant",
-      platformAssistantId: "platform-assistant-1",
-      platformBaseUrl: "https://platform.example.test",
-      platformOrganizationId: "org-123",
+      cloudAssistantId: "cloud-asst-1",
     });
     writeLockfile([entry]);
-    readPlatformTokenMock.mockReturnValue("session-token");
-    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
-    readGatewayCredentialMock.mockResolvedValue({
-      value: null,
-      unreachable: true,
-    });
+    readCloudTokenMock.mockReturnValue("session-token");
+    getCloudUrlMock.mockReturnValue("https://platform.example.test");
     process.argv = ["bun", "cadet", "retire", "assistant-1", "--yes"];
 
     await retire();
 
-    expect(readGatewayCredentialMock).toHaveBeenCalledWith(
-      entry.localUrl ?? entry.runtimeUrl,
-      "cadet:platform_assistant_id",
-      entry.bearerToken,
+    expect(authHeadersMock).toHaveBeenCalledWith(
+      "session-token",
+      "https://platform.example.test",
     );
+    expect(authHeadersForKnownOrganizationMock).not.toHaveBeenCalled();
     expect(loopbackSafeFetchMock).toHaveBeenCalledWith(
-      "https://platform.example.test/v1/assistants/platform-assistant-1/retire/",
+      "https://platform.example.test/v1/assistants/cloud-asst-1/retire/",
       {
         method: "DELETE",
         headers: {
           "Content-Type": "application/json",
           "X-Session-Token": "session-token",
-          "Cadet-Organization-Id": "org-123",
         },
       },
     );
-    expect(consoleWarnSpy.mock.calls.flat().join("\n")).toContain(
-      "using saved platform registration",
-    );
     expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
     expect(loadAllAssistants()).toEqual([]);
   });
 
-  test("local retire continues when local credentials are unreachable and no saved platform registration exists", async () => {
+  test("local retire skips the cloud unregister when no assistant id is bound", async () => {
     const entry = makeEntry("assistant-1", { name: "Example Assistant" });
     writeLockfile([entry]);
-    readPlatformTokenMock.mockReturnValue("session-token");
-    readGatewayCredentialMock.mockResolvedValue({
-      value: null,
-      unreachable: true,
-    });
+    readCloudTokenMock.mockReturnValue("session-token");
+    getCloudUrlMock.mockReturnValue("https://platform.example.test");
     process.argv = ["bun", "cadet", "retire", "assistant-1", "--yes"];
 
     await retire();
 
     expect(loopbackSafeFetchMock).not.toHaveBeenCalled();
-    expect(consoleWarnSpy.mock.calls.flat().join("\n")).toContain(
-      "no saved platform registration is available",
-    );
-    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
-    expect(loadAllAssistants()).toEqual([]);
-  });
-
-  test("local retire skips platform unregister when stored platform URL origin mismatches", async () => {
-    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
-    writeLockfile([entry]);
-    readPlatformTokenMock.mockReturnValue("session-token");
-    getPlatformUrlMock.mockReturnValue("https://platform.example.com");
-    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
-      if (name === "cadet:platform_assistant_id") {
-        return { value: "platform-assistant-1", unreachable: false };
-      }
-      if (name === "cadet:platform_base_url") {
-        return { value: "https://malicious.example.test", unreachable: false };
-      }
-      if (name === "cadet:platform_organization_id") {
-        return { value: "org-123", unreachable: false };
-      }
-      return { value: null, unreachable: false };
-    });
-    process.argv = ["bun", "cadet", "retire", "assistant-1", "--yes"];
-
-    await retire();
-
-    expect(loopbackSafeFetchMock).not.toHaveBeenCalled();
-    expect(consoleWarnSpy.mock.calls.flat().join("\n")).toContain(
-      "Stored platform URL does not match the configured platform URL",
-    );
-    expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
-  });
-
-  test("local retire skips platform unregister when stored organization ID is missing", async () => {
-    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
-    writeLockfile([entry]);
-    readPlatformTokenMock.mockReturnValue("session-token");
-    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
-    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
-      if (name === "cadet:platform_assistant_id") {
-        return { value: "platform-assistant-1", unreachable: false };
-      }
-      if (name === "cadet:platform_base_url") {
-        return { value: "https://platform.example.test", unreachable: false };
-      }
-      return { value: null, unreachable: false };
-    });
-    process.argv = ["bun", "cadet", "retire", "assistant-1", "--yes"];
-
-    await retire();
-
-    expect(loopbackSafeFetchMock).not.toHaveBeenCalled();
-    expect(consoleWarnSpy.mock.calls.flat().join("\n")).toContain(
-      "Could not read platform organization ID",
-    );
     expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
     expect(loadAllAssistants()).toEqual([]);
   });
 
   test("local retire uses injected platform token from the app host", async () => {
-    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
+    const entry = makeEntry("assistant-1", {
+      name: "Example Assistant",
+      cloudAssistantId: "cloud-asst-1",
+      cloudOrganizationId: "org-123",
+    });
     writeLockfile([entry]);
     process.env.CADET_PLATFORM_TOKEN = "host-session-token";
-    readPlatformTokenMock.mockReturnValue(null);
-    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
-    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
-      if (name === "cadet:platform_assistant_id") {
-        return { value: "platform-assistant-1", unreachable: false };
-      }
-      if (name === "cadet:platform_base_url") {
-        return { value: "https://platform.example.test", unreachable: false };
-      }
-      if (name === "cadet:platform_organization_id") {
-        return { value: "org-123", unreachable: false };
-      }
-      return { value: null, unreachable: false };
-    });
+    readCloudTokenMock.mockReturnValue(null);
+    getCloudUrlMock.mockReturnValue("https://platform.example.test");
     process.argv = ["bun", "cadet", "retire", "assistant-1", "--yes"];
 
     await retire();
 
     expect(loopbackSafeFetchMock).toHaveBeenCalledWith(
-      "https://platform.example.test/v1/assistants/platform-assistant-1/retire/",
+      "https://platform.example.test/v1/assistants/cloud-asst-1/retire/",
       {
         method: "DELETE",
         headers: {
@@ -494,23 +361,15 @@ describe("cadet retire", () => {
     expect(retireLocalMock).toHaveBeenCalledWith("assistant-1", entry);
   });
 
-  test("local retire continues when self-hosted platform unregister fails", async () => {
-    const entry = makeEntry("assistant-1", { name: "Example Assistant" });
-    writeLockfile([entry]);
-    readPlatformTokenMock.mockReturnValue("session-token");
-    getPlatformUrlMock.mockReturnValue("https://platform.example.test");
-    readGatewayCredentialMock.mockImplementation(async (_gatewayUrl, name) => {
-      if (name === "cadet:platform_assistant_id") {
-        return { value: "platform-assistant-1", unreachable: false };
-      }
-      if (name === "cadet:platform_base_url") {
-        return { value: "https://platform.example.test", unreachable: false };
-      }
-      if (name === "cadet:platform_organization_id") {
-        return { value: "org-123", unreachable: false };
-      }
-      return { value: null, unreachable: false };
+  test("local retire continues when the cloud unregister fails", async () => {
+    const entry = makeEntry("assistant-1", {
+      name: "Example Assistant",
+      cloudAssistantId: "cloud-asst-1",
+      cloudOrganizationId: "org-123",
     });
+    writeLockfile([entry]);
+    readCloudTokenMock.mockReturnValue("session-token");
+    getCloudUrlMock.mockReturnValue("https://platform.example.test");
     loopbackSafeFetchMock.mockResolvedValue(
       new Response("platform unavailable", { status: 503 }),
     );

package/src/__tests__/root-process-lockfile.test.ts

@@ -0,0 +1,99 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { z } from "zod";
+
+import {
+  clearRootProcess,
+  readRootProcesses,
+  stampRootProcess,
+} from "../lib/assistant-config.js";
+
+// Create a temp directory and set CADET_LOCKFILE_DIR so the real lockfile
+// helpers resolve inside it (the sleep.test.ts fixture pattern).
+let testDir: string;
+
+beforeEach(() => {
+  testDir = mkdtempSync(join(tmpdir(), "cadet-root-process-test-"));
+  mkdirSync(join(testDir, "config"), { recursive: true });
+  process.env.CADET_LOCKFILE_DIR = join(testDir, "config");
+});
+
+afterEach(() => {
+  delete process.env.CADET_LOCKFILE_DIR;
+  rmSync(testDir, { recursive: true, force: true });
+});
+
+describe("root process lockfile entries", () => {
+  test("a tunnel record stamps at the root, reads back, and clears", () => {
+    stampRootProcess("tunnel", {
+      pid: 4242,
+      provider: "ngrok",
+      startedAt: "2026-10-11T00:00:00.000Z",
+    });
+
+    expect(readRootProcesses().tunnel).toMatchObject({
+      pid: 4242,
+      provider: "ngrok",
+    });
+
+    clearRootProcess("tunnel");
+    expect(readRootProcesses().tunnel).toBeUndefined();
+  });
+
+  test("tunnel and app entries stamp and clear independently", () => {
+    stampRootProcess("app", { pid: 77, startedAt: "2026-10-11T00:00:00.000Z" });
+    stampRootProcess("tunnel", {
+      pid: 78,
+      provider: "cloudflare",
+      startedAt: "2026-10-11T00:00:00.000Z",
+    });
+
+    expect(readRootProcesses().app?.pid).toBe(77);
+    expect(readRootProcesses().tunnel?.provider).toBe("cloudflare");
+
+    clearRootProcess("app");
+    expect(readRootProcesses().app).toBeUndefined();
+    // The sibling entry survives.
+    expect(readRootProcesses().tunnel?.pid).toBe(78);
+  });
+
+  test("a record can name the assistant it fronts, for `cadet ps` nesting", () => {
+    stampRootProcess("tunnel", {
+      pid: 4242,
+      provider: "ngrok",
+      startedAt: "2026-10-11T00:00:00.000Z",
+      assistantId: "assistant-1",
+    });
+
+    expect(readRootProcesses().tunnel).toMatchObject({
+      pid: 4242,
+      provider: "ngrok",
+      assistantId: "assistant-1",
+    });
+  });
+
+  test("the records live at the lockfile root under their kind keys", () => {
+    stampRootProcess("app", { pid: 1, startedAt: "t" });
+
+    const raw = z
+      .object({
+        app: z.object({ pid: z.number(), startedAt: z.string() }),
+      })
+      .parse(
+        JSON.parse(
+          readFileSync(
+            join(process.env.CADET_LOCKFILE_DIR!, "lockfile.json"),
+            "utf-8",
+          ),
+        ),
+      );
+    expect(raw.app).toEqual({ pid: 1, startedAt: "t" });
+  });
+
+  test("clearing an absent entry is a no-op", () => {
+    clearRootProcess("tunnel");
+    expect(readRootProcesses()).toEqual({});
+  });
+});