@jaybeeuu/agent-cortex 1.39.0 → 1.41.0

package/test/cli.test.mjs

@@ -1,7 +1,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -10,104 +10,125 @@ import { parseArgs, buildHelpText, validateHarness } from "../lib/cli.mjs";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI_PATH = join(__dirname, "..", "bin", "agent-cortex.mjs");
 
-function runCli(args) {
+/** True when a path exists (stat succeeds). */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Run the CLI; optionally pass a custom env (e.g. a fake HOME). */
+function runCli(args, env = {}) {
   return new Promise((resolve) => {
-    execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
-      resolve({
-        exitCode: error ? error.code ?? 1 : 0,
-        stdout: stdout,
-        stderr: stderr,
-      });
-    });
+    execFile(
+      process.execPath,
+      [CLI_PATH, ...args],
+      { env: { ...process.env, ...env } },
+      (error, stdout, stderr) => {
+        resolve({
+          exitCode: error ? error.code ?? 1 : 0,
+          stdout: stdout,
+          stderr: stderr,
+        });
+      },
+    );
   });
 }
 
 describe("parseArgs", () => {
-  it("returns { command: 'help' } when no arguments given", () => {
+  it("returns { command: 'help' } when no arguments given", async () => {
     const result = parseArgs([]);
     assert.deepStrictEqual(result, { command: "help" });
   });
 
-  it("returns { command: 'help' } for --help flag", () => {
+  it("returns { command: 'help' } for --help flag", async () => {
     const result = parseArgs(["--help"]);
     assert.deepStrictEqual(result, { command: "help" });
   });
 
-  it("returns { command: 'help' } for -h flag", () => {
+  it("returns { command: 'help' } for -h flag", async () => {
     const result = parseArgs(["-h"]);
     assert.deepStrictEqual(result, { command: "help" });
   });
 
-  it("returns { command: 'install', harness: 'copilot' } for install copilot", () => {
+  it("returns { command: 'install', harness: 'copilot' } for install copilot", async () => {
     const result = parseArgs(["install", "copilot"]);
     assert.deepStrictEqual(result, { command: "install", harness: "copilot" });
   });
 
-  it("returns { command: 'install', harness: 'claude' } for install claude", () => {
+  it("returns { command: 'install', harness: 'claude' } for install claude", async () => {
     const result = parseArgs(["install", "claude"]);
     assert.deepStrictEqual(result, { command: "install", harness: "claude" });
   });
 
-  it("returns { command: 'install', harness: 'pi' } for install pi", () => {
+  it("returns { command: 'install', harness: 'pi' } for install pi", async () => {
     const result = parseArgs(["install", "pi"]);
     assert.deepStrictEqual(result, { command: "install", harness: "pi" });
   });
 
-  it("returns { command: 'install', harness: null } when install has no harness", () => {
+  it("returns { command: 'install', harness: null } when install has no harness", async () => {
     const result = parseArgs(["install"]);
     assert.deepStrictEqual(result, { command: "install", harness: null });
   });
 
-  it("returns output for install claude --output <dir>", () => {
+  it("returns output for install claude --output <dir>", async () => {
     const result = parseArgs(["install", "claude", "--output", "/tmp/x"]);
     assert.deepStrictEqual(result, { command: "install", harness: "claude", output: "/tmp/x" });
   });
 
-  it("returns output for install claude --output=<dir>", () => {
+  it("returns output for install claude --output=<dir>", async () => {
     const result = parseArgs(["install", "claude", "--output=/tmp/x"]);
     assert.deepStrictEqual(result, { command: "install", harness: "claude", output: "/tmp/x" });
   });
 
-  it("returns dryRun for install claude --dry-run", () => {
+  it("returns dryRun for install claude --dry-run", async () => {
     const result = parseArgs(["install", "claude", "--dry-run"]);
     assert.deepStrictEqual(result, { command: "install", harness: "claude", dryRun: true });
   });
 
-  it("combines --dry-run with --output", () => {
+  it("combines --dry-run with --output", async () => {
     const result = parseArgs(["install", "claude", "--output", "/tmp/x", "--dry-run"]);
     assert.deepStrictEqual(result, { command: "install", harness: "claude", output: "/tmp/x", dryRun: true });
   });
 
-  it("reports an unknown option for claude", () => {
+  it("reports an unknown option for claude", async () => {
     const result = parseArgs(["install", "claude", "--bogus"]);
     assert.equal(result.command, "install");
     assert.equal(result.harness, "claude");
     assert.ok(result.optionError.includes("--bogus"));
   });
 
-  it("reports a missing value for --output for claude", () => {
+  it("reports a missing value for --output for claude", async () => {
     const result = parseArgs(["install", "claude", "--output"]);
     assert.equal(result.command, "install");
     assert.equal(result.harness, "claude");
     assert.ok(result.optionError.includes("--output"));
   });
 
-  it("parses --dry-run for install", () => {
+  it("parses --dry-run for install", async () => {
     const result = parseArgs(["install", "pi", "--dry-run"]);
     assert.deepStrictEqual(result, { command: "install", harness: "pi", dryRun: true });
   });
 
-  it("parses --output <dir> for install", () => {
+  it("parses --output <dir> for install", async () => {
     const result = parseArgs(["install", "pi", "--output", "/tmp/out"]);
     assert.deepStrictEqual(result, { command: "install", harness: "pi", output: "/tmp/out" });
   });
 
-  it("parses --plugin-root <dir> for install", () => {
+  it("parses --plugin-root <dir> for install", async () => {
     const result = parseArgs(["install", "pi", "--plugin-root", "/tmp/plugin"]);
     assert.deepStrictEqual(result, { command: "install", harness: "pi", pluginRoot: "/tmp/plugin" });
   });
 
-  it("combines multiple install options", () => {
+  it("parses --no-provision for install", async () => {
+    const result = parseArgs(["install", "pi", "--no-provision"]);
+    assert.deepStrictEqual(result, { command: "install", harness: "pi", noProvision: true });
+  });
+
+  it("combines multiple install options", async () => {
     const result = parseArgs(["install", "pi", "--dry-run", "--output", "/tmp/out", "--plugin-root", "/tmp/plugin"]);
     assert.deepStrictEqual(result, {
       command: "install",
@@ -118,32 +139,32 @@ describe("parseArgs", () => {
     });
   });
 
-  it("reports a missing value for --output", () => {
+  it("reports a missing value for --output", async () => {
     const result = parseArgs(["install", "pi", "--output"]);
     assert.equal(result.command, "install");
     assert.equal(result.harness, "pi");
     assert.ok(result.optionError.includes("--output"));
   });
 
-  it("reports an unknown option", () => {
+  it("reports an unknown option", async () => {
     const result = parseArgs(["install", "pi", "--bogus"]);
     assert.equal(result.command, "install");
     assert.equal(result.harness, "pi");
     assert.ok(result.optionError.includes("--bogus"));
   });
 
-  it("keeps the old shape when no options are given", () => {
+  it("keeps the old shape when no options are given", async () => {
     assert.deepStrictEqual(parseArgs(["install", "pi"]), { command: "install", harness: "pi" });
   });
 
-  it("returns { command: 'unknown', name: 'foo' } for unknown command", () => {
+  it("returns { command: 'unknown', name: 'foo' } for unknown command", async () => {
     const result = parseArgs(["foo"]);
     assert.deepStrictEqual(result, { command: "unknown", name: "foo" });
   });
 });
 
 describe("buildHelpText", () => {
-  it("returns a string containing usage info", () => {
+  it("returns a string containing usage info", async () => {
     const text = buildHelpText();
     assert.ok(typeof text === "string");
     assert.ok(text.includes("agent-cortex"));
@@ -152,19 +173,19 @@ describe("buildHelpText", () => {
 });
 
 describe("validateHarness", () => {
-  it("returns ok for supported harnesses", () => {
+  it("returns ok for supported harnesses", async () => {
     for (const h of ["copilot", "claude", "pi"]) {
       assert.deepStrictEqual(validateHarness(h), { ok: true });
     }
   });
 
-  it("returns error when harness is null", () => {
+  it("returns error when harness is null", async () => {
     const result = validateHarness(null);
     assert.equal(result.ok, false);
     assert.ok(result.error.includes("Missing harness"));
   });
 
-  it("returns error for unknown harness", () => {
+  it("returns error for unknown harness", async () => {
     const result = validateHarness("docker");
     assert.equal(result.ok, false);
     assert.ok(result.error.includes("Unknown harness"));
@@ -198,14 +219,27 @@ describe("CLI integration", () => {
   });
 
   it("exits 0 for install claude (into a temp output dir)", async () => {
-    const dir = mkdtempSync(join(tmpdir(), "agent-cortex-cli-"));
+    const dir = await mkdtemp(join(tmpdir(), "agent-cortex-cli-"));
     const { exitCode, stdout } = await runCli(["install", "claude", "--output", dir]);
     assert.equal(exitCode, 0);
     assert.ok(stdout.includes("claude"));
   });
 
-  it("exits 0 for install pi", async () => {
-    const { exitCode, stdout } = await runCli(["install", "pi"]);
+  it("exits 0 for install pi (into a temp output dir)", async () => {
+    const outDir = await mkdtemp(join(tmpdir(), "cli-pi-default-"));
+    try {
+      const { exitCode, stdout } = await runCli(["install", "pi", "--output", outDir]);
+      assert.equal(exitCode, 0);
+      assert.ok(stdout.includes("pi"));
+    } finally {
+      await rm(outDir, { recursive: true, force: true });
+    }
+  });
+
+  it("exits 0 for install pi --no-provision", async () => {
+    // --no-provision keeps this hermetic: without it the CLI would install the
+    // third-party packages declared in the package manifest.
+    const { exitCode, stdout } = await runCli(["install", "pi", "--no-provision"]);
     assert.equal(exitCode, 0);
     assert.ok(stdout.includes("pi"));
   });
@@ -235,16 +269,36 @@ describe("CLI integration", () => {
     assert.ok(stdout.includes("dry-run"));
   });
 
-  it("exits 0 for install pi --output <tmp> and writes agent files", async () => {
-    const outDir = mkdtempSync(join(tmpdir(), "cli-pi-install-"));
+  it("install pi --dry-run lists the pi packages it would install", async () => {
+    // Fake HOME keeps the pi user scope hermetic: both manifest packages are
+    // missing, so the plan contains exactly the declared sources.
+    const fakeHome = await mkdtemp(join(tmpdir(), "cli-pi-home-"));
+    try {
+      const { exitCode, stdout } = await runCli(["install", "pi", "--dry-run"], { HOME: fakeHome });
+      assert.equal(exitCode, 0);
+      assert.ok(stdout.includes("Would install pi package npm:pi-questions"), "planned pi-questions shown");
+      assert.ok(
+        stdout.includes("Would install pi package npm:pi-web-access@0.10.7"),
+        "planned pi-web-access shown",
+      );
+    } finally {
+      await rm(fakeHome, { recursive: true, force: true });
+    }
+  });
+
+  it("exits 0 for install pi --output <tmp> and writes agent and config files", async () => {
+    const outDir = await mkdtemp(join(tmpdir(), "cli-pi-install-"));
     try {
       const { exitCode, stdout } = await runCli(["install", "pi", "--output", outDir]);
       assert.equal(exitCode, 0);
       assert.ok(stdout.includes("ralph.agent.md"));
-      const ralph = readFileSync(join(outDir, "agents", "ralph.agent.md"), "utf-8");
+      const ralph = await readFile(join(outDir, "agents", "ralph.agent.md"), "utf-8");
       assert.ok(ralph.includes("agent-cortex:ralph"));
+      const settings = JSON.parse(await readFile(join(outDir, "settings.json"), "utf-8"));
+      assert.ok(Array.isArray(settings.packages));
+      assert.ok(await readFile(join(outDir, "keybindings.json"), "utf-8"));
     } finally {
-      rmSync(outDir, { recursive: true, force: true });
+      await rm(outDir, { recursive: true, force: true });
     }
   });
 

package/test/copilot-installer.test.mjs

@@ -5,7 +5,7 @@
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { mkdtemp, mkdir, writeFile, rm, readFile, readdir, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { join, dirname } from "node:path";
@@ -15,6 +15,16 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, "..");
 const CLI_PATH = join(ROOT, "bin", "agent-cortex.mjs");
 
+/** True when a path exists (stat succeeds). */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function runCli(args) {
   return new Promise((resolve) => {
     execFile(process.execPath, [CLI_PATH, ...args], (error, stdout, stderr) => {
@@ -43,28 +53,28 @@ function tokenMap() {
   };
 }
 
-function makeFixture() {
-  const root = mkdtempSync(join(tmpdir(), "copilot-installer-"));
+async function makeFixture() {
+  const root = await mkdtemp(join(tmpdir(), "copilot-installer-"));
   return {
     root,
     output: join(root, "generated"),
-    cleanup: () => rmSync(root, { recursive: true, force: true }),
+    cleanup: async () => rm(root, { recursive: true, force: true }),
   };
 }
 
-function writeFixture(fx, relPath, content) {
+async function writeFixture(fx, relPath, content) {
   const p = join(fx.root, relPath);
-  mkdirSync(dirname(p), { recursive: true });
-  writeFileSync(p, content);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, content);
 }
 
 /** Seed a minimal but realistic package tree (agents + token-map). */
-function seedCopilotPackage(fx, opts = {}) {
+async function seedCopilotPackage(fx, opts = {}) {
   const { agents = {} } = opts;
-  writeFixture(fx, "token-map.json", JSON.stringify(tokenMap()));
+  await writeFixture(fx, "token-map.json", JSON.stringify(tokenMap()));
   for (const [name, def] of Object.entries(agents)) {
-    writeFixture(fx, `agents/${name}/agent.md`, def.body ?? `# ${name}\nBody of ${name}.`);
-    writeFixture(
+    await writeFixture(fx, `agents/${name}/agent.md`, def.body ?? `# ${name}\nBody of ${name}.`);
+    await writeFixture(
       fx,
       `agents/${name}/copilot/frontmatter.json`,
       JSON.stringify(
@@ -77,34 +87,34 @@ function seedCopilotPackage(fx, opts = {}) {
       ),
     );
     for (const [section, content] of Object.entries(def.sections ?? {})) {
-      writeFixture(fx, `agents/${name}/copilot/${section}.md`, content);
+      await writeFixture(fx, `agents/${name}/copilot/${section}.md`, content);
     }
   }
 }
 
 /** Deterministic snapshot of a directory: relative paths + byte content. */
-function snapshot(dir) {
+async function snapshot(dir) {
   const entries = [];
-  const walk = (p) => {
-    for (const e of readdirSync(p, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+  const walk = async (p) => {
+    for (const e of (await readdir(p, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
       const full = join(p, e.name);
       if (e.isDirectory()) {
         entries.push([e.name, "dir"]);
-        walk(full);
-      } else entries.push([e.name, "file", readFileSync(full, "utf-8")]);
+        await walk(full);
+      } else entries.push([e.name, "file", await readFile(full, "utf-8")]);
     }
   };
-  walk(dir);
+  await walk(dir);
   return entries;
 }
 
 // ─── Agent composition ───────────────────────────────────────────────────────
 
 describe("installCopilot — agent composition", () => {
-  it("writes one flat <name>.agent.md per composable agent dir with copilot frontmatter and no leftover tokens", () => {
-    const fx = makeFixture();
+  it("writes one flat <name>.agent.md per composable agent dir with copilot frontmatter and no leftover tokens", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, {
+      await seedCopilotPackage(fx, {
         agents: {
           alpha: {
             body: "# alpha\nUse {{TOOL:view}} to read.\n{{SECTION:polling}}\nRead {{PATH:agents_dir}}.",
@@ -119,11 +129,11 @@ describe("installCopilot — agent composition", () => {
         },
       });
 
-      const result = installCopilot({ root: fx.root, output: fx.output });
+      const result = await installCopilot({ root: fx.root, output: fx.output });
 
       const file = join(fx.output, "alpha.agent.md");
-      assert.ok(existsSync(file), "flat agent file written");
-      const content = readFileSync(file, "utf-8");
+      assert.ok(await pathExists(file), "flat agent file written");
+      const content = await readFile(file, "utf-8");
       assert.ok(content.startsWith("---\n"), "yaml frontmatter");
       assert.ok(content.includes("# GENERATED from agents/alpha/ by scripts/build-copilot-agents.mjs — DO NOT EDIT."));
       // Committed flat-file field order: description, name, tools (YAML array), argument-hint.
@@ -138,64 +148,64 @@ describe("installCopilot — agent composition", () => {
       assert.deepEqual(result.agents, ["alpha"]);
       assert.equal(result.output, fx.output);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("skips non-composable entries in agents/ and never clobbers composable sources", () => {
-    const fx = makeFixture();
+  it("skips non-composable entries in agents/ and never clobbers composable sources", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
-      writeFixture(fx, "agents/README.md", "# agents dir docs\n");
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await writeFixture(fx, "agents/README.md", "# agents dir docs\n");
 
-      const result = installCopilot({ root: fx.root, output: fx.output });
+      const result = await installCopilot({ root: fx.root, output: fx.output });
 
-      assert.deepEqual(readdirSync(fx.output).sort(), ["alpha.agent.md"], "no README, no subdirectories written");
+      assert.deepEqual((await readdir(fx.output)).sort(), ["alpha.agent.md"], "no README, no subdirectories written");
       assert.deepEqual(result.agents, ["alpha"]);
       // The composable source dir next to the generated file stays untouched.
-      assert.ok(existsSync(join(fx.root, "agents", "alpha", "agent.md")), "composable source preserved");
-      assert.ok(existsSync(join(fx.root, "agents", "alpha", "copilot", "frontmatter.json")), "harness dir preserved");
+      assert.ok(await pathExists(join(fx.root, "agents", "alpha", "agent.md")), "composable source preserved");
+      assert.ok(await pathExists(join(fx.root, "agents", "alpha", "copilot", "frontmatter.json")), "harness dir preserved");
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("throws when a composable dir lacks copilot/frontmatter.json", () => {
-    const fx = makeFixture();
+  it("throws when a composable dir lacks copilot/frontmatter.json", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
-      rmSync(join(fx.root, "agents", "alpha", "copilot"), { recursive: true, force: true });
-      assert.throws(
-        () => installCopilot({ root: fx.root, output: fx.output }),
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await rm(join(fx.root, "agents", "alpha", "copilot"), { recursive: true, force: true });
+      await assert.rejects(
+        installCopilot({ root: fx.root, output: fx.output }),
         /without copilot\/frontmatter\.json/,
       );
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("defaults to the plugin-scanned agents/ dir of the package root (plugin.json \"agents\": \"agents/\")", () => {
-    const fx = makeFixture();
+  it("defaults to the plugin-scanned agents/ dir of the package root (plugin.json \"agents\": \"agents/\")", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
 
-      const result = installCopilot({ root: fx.root });
+      const result = await installCopilot({ root: fx.root });
 
       assert.equal(result.output, join(fx.root, "agents"), "default output is the dir plugin.json scans");
-      assert.ok(existsSync(join(fx.root, "agents", "alpha.agent.md")), "flat file lands next to the composable dir");
-      assert.ok(existsSync(join(fx.root, "agents", "alpha", "agent.md")), "composable source untouched");
+      assert.ok(await pathExists(join(fx.root, "agents", "alpha.agent.md")), "flat file lands next to the composable dir");
+      assert.ok(await pathExists(join(fx.root, "agents", "alpha", "agent.md")), "composable source untouched");
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("throws on an unknown tool token", () => {
-    const fx = makeFixture();
+  it("throws on an unknown tool token", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha\nUse {{TOOL:nope}} now." } } });
-      assert.throws(() => installCopilot({ root: fx.root, output: fx.output }), /unknown tool token {{TOOL:nope}}/);
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha\nUse {{TOOL:nope}} now." } } });
+      await assert.rejects(installCopilot({ root: fx.root, output: fx.output }), /unknown tool token {{TOOL:nope}}/);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });
@@ -203,37 +213,37 @@ describe("installCopilot — agent composition", () => {
 // ─── Output / dry-run ────────────────────────────────────────────────────────
 
 describe("installCopilot — output & dry-run", () => {
-  it("dry-run reports the plan without writing anything", () => {
-    const fx = makeFixture();
+  it("dry-run reports the plan without writing anything", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
+      await seedCopilotPackage(fx, { agents: { alpha: { body: "# alpha" } } });
 
-      const result = installCopilot({ root: fx.root, output: fx.output, dryRun: true });
+      const result = await installCopilot({ root: fx.root, output: fx.output, dryRun: true });
 
       assert.equal(result.dryRun, true);
-      assert.equal(existsSync(fx.output), false, "no output dir created in dry-run");
+      assert.equal(await pathExists(fx.output), false, "no output dir created in dry-run");
       assert.deepEqual(result.agents, ["alpha"], "planned files still reported");
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
-  it("is deterministic across repeated installs into the same output", () => {
-    const fx = makeFixture();
+  it("is deterministic across repeated installs into the same output", async () => {
+    const fx = await makeFixture();
     try {
-      seedCopilotPackage(fx, {
+      await seedCopilotPackage(fx, {
         agents: {
           alpha: { body: "# alpha\n{{SECTION:polling}}", sections: { polling: "Poll with {{TOOL:task}}." } },
           beta: { body: "# beta" },
         },
       });
 
-      installCopilot({ root: fx.root, output: fx.output });
-      const first = snapshot(fx.output);
-      installCopilot({ root: fx.root, output: fx.output });
-      assert.deepEqual(snapshot(fx.output), first);
+      await installCopilot({ root: fx.root, output: fx.output });
+      const first = await snapshot(fx.output);
+      await installCopilot({ root: fx.root, output: fx.output });
+      assert.deepEqual(await snapshot(fx.output), first);
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });
@@ -241,19 +251,19 @@ describe("installCopilot — output & dry-run", () => {
 // ─── Integration against the real repo ───────────────────────────────────────
 
 describe("installCopilot — real repo integration", () => {
-  it("regenerates byte-identical copies of the committed agents/*.agent.md files", () => {
-    const fx = makeFixture();
+  it("regenerates byte-identical copies of the committed agents/*.agent.md files", async () => {
+    const fx = await makeFixture();
     try {
-      const result = installCopilot({ root: ROOT, output: fx.output });
+      const result = await installCopilot({ root: ROOT, output: fx.output });
 
       assert.deepEqual(result.agents.sort(), ["plan", "ralph", "ralph-plan", "strategy"]);
       for (const name of result.agents) {
-        const generated = readFileSync(join(fx.output, `${name}.agent.md`), "utf-8");
-        const committed = readFileSync(join(ROOT, "agents", `${name}.agent.md`), "utf-8");
+        const generated = await readFile(join(fx.output, `${name}.agent.md`), "utf-8");
+        const committed = await readFile(join(ROOT, "agents", `${name}.agent.md`), "utf-8");
         assert.equal(generated, committed, `${name}.agent.md must match the committed flat file (CI drift check)`);
       }
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 });
@@ -262,37 +272,37 @@ describe("installCopilot — real repo integration", () => {
 
 describe("CLI integration", () => {
   it("exits 0 for install copilot --output <tmp> and writes the flat files", async () => {
-    const fx = makeFixture();
+    const fx = await makeFixture();
     try {
       const { exitCode, stdout } = await runCli(["install", "copilot", "--output", fx.output]);
       assert.equal(exitCode, 0);
       assert.ok(stdout.includes("copilot"), "prints the harness name");
       assert.ok(stdout.includes("Generated"), "prints the generation summary");
-      assert.ok(existsSync(join(fx.output, "ralph.agent.md")), "agent files written");
-      assert.ok(existsSync(join(fx.output, "plan.agent.md")));
+      assert.ok(await pathExists(join(fx.output, "ralph.agent.md")), "agent files written");
+      assert.ok(await pathExists(join(fx.output, "plan.agent.md")));
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
   it("exits 0 for install copilot --dry-run and writes nothing", async () => {
-    const fx = makeFixture();
+    const fx = await makeFixture();
     try {
       const { exitCode, stdout } = await runCli(["install", "copilot", "--output", fx.output, "--dry-run"]);
       assert.equal(exitCode, 0);
       assert.ok(/dry-run/i.test(stdout));
-      assert.equal(existsSync(fx.output), false, "no files written in dry-run");
+      assert.equal(await pathExists(fx.output), false, "no files written in dry-run");
     } finally {
-      fx.cleanup();
+      await fx.cleanup();
     }
   });
 
   it("exits 0 for install copilot (default output) without touching committed files", async () => {
-    const before = readFileSync(join(ROOT, "agents", "ralph.agent.md"), "utf-8");
+    const before = await readFile(join(ROOT, "agents", "ralph.agent.md"), "utf-8");
     const { exitCode } = await runCli(["install", "copilot"]);
     assert.equal(exitCode, 0);
     // Default output regenerates the shared agents/ dir in place — output must
     // stay byte-identical to what is committed.
-    assert.equal(readFileSync(join(ROOT, "agents", "ralph.agent.md"), "utf-8"), before);
+    assert.equal(await readFile(join(ROOT, "agents", "ralph.agent.md"), "utf-8"), before);
   });
 });