@jaybeeuu/agent-cortex 1.39.0 → 1.40.0

package/bin/installers/copilot.mjs

@@ -30,7 +30,7 @@
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { writeFileSync, mkdirSync, readdirSync, statSync, existsSync } from "node:fs";
+import { writeFile, mkdir, readdir, stat } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
@@ -38,9 +38,17 @@ import { composeAgent } from "../../scripts/lib/compose-agent.mjs";
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_ROOT = join(MODULE_DIR, "..", "..");
 
-function isDirectory(p) {
+async function isDirectory(p) {
   try {
-    return statSync(p).isDirectory();
+    return (await stat(p)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function isFile(p) {
+  try {
+    return (await stat(p)).isFile();
   } catch {
     return false;
   }
@@ -71,19 +79,21 @@ function frontmatterYaml(name, fm) {
 }
 
 /** Compose agents from agents/<name>/; every composable dir must ship a copilot harness. */
-function buildAgents(root) {
+async function buildAgents(root) {
   const files = [];
-  const entries = readdirSync(join(root, "agents"), { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+  const entries = (await readdir(join(root, "agents"), { withFileTypes: true })).sort((a, b) =>
+    byName(a.name, b.name),
+  );
 
   for (const entry of entries) {
     if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files and README
     const dir = join(root, "agents", entry.name);
-    if (!existsSync(join(dir, "agent.md"))) continue; // not a composable agent dir
-    if (!isDirectory(join(dir, "copilot")) || !existsSync(join(dir, "copilot", "frontmatter.json"))) {
+    if (!(await isFile(join(dir, "agent.md")))) continue; // not a composable agent dir
+    if (!(await isDirectory(join(dir, "copilot"))) || !(await isFile(join(dir, "copilot", "frontmatter.json")))) {
       throw new Error(`agent "${entry.name}": composable directory without copilot/frontmatter.json — define the copilot harness or exclude the agent`);
     }
 
-    const fm = composeAgent(root, entry.name, "copilot");
+    const fm = await composeAgent(root, entry.name, "copilot");
     files.push({
       name: entry.name,
       file: `${entry.name}.agent.md`,
@@ -105,9 +115,9 @@ function buildAgents(root) {
  * @param {boolean} [options.dryRun] Plan and report without writing anything.
  * @returns {{ output: string, agents: string[], dryRun: boolean }}
  */
-export function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
+export async function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } = {}) {
   const out = output ?? join(root, "agents");
-  const files = buildAgents(root);
+  const files = await buildAgents(root);
   const summary = {
     output: out,
     agents: files.map((f) => f.name),
@@ -120,9 +130,9 @@ export function installCopilot({ root = DEFAULT_ROOT, output, dryRun = false } =
     return summary;
   }
 
-  mkdirSync(out, { recursive: true });
+  await mkdir(out, { recursive: true });
   for (const { file, content } of files) {
-    writeFileSync(join(out, file), content);
+    await writeFile(join(out, file), content);
   }
   console.log(`Generated ${files.length} Copilot agent file(s): ${summary.agents.join(", ")}`);
   return summary;

package/bin/installers/pi.mjs

@@ -8,8 +8,9 @@
 // Composition per the token-map.json contract:
 //   1. {{SECTION:name}} is resolved from the agent's pi/<name>.md section file
 //      (shared composer, scripts/lib/compose-agent.mjs).
-//   2. {{TOOL:key}} is substituted with the pi column; a null mapping drops the
-//      token from prose with a warning (pi has no ask_user/skill tool).
+//   2. {{TOOL:key}} is substituted with the pi column (pi maps ask_user →
+//      ask_questions and skill → read); any (future) null pi mapping drops the
+//      token from prose with a warning.
 //   3. {{PATH:key}} named keys resolve through the paths table; bare relative
 //      paths resolve against the plugin root (default: token-map.json's pi value,
 //      overridable with --plugin-root for checkout/symlinked installs).
@@ -24,7 +25,7 @@
 //
 // Zero dependencies so it runs on the CI Node and local Node alike.
 
-import { readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, statSync } from "node:fs";
+import { readFile, writeFile, mkdir, copyFile, readdir, stat } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -37,22 +38,22 @@ const PI = "pi";
 // extended before this installer can trust it.
 const CONTRACT_VERSION = 1;
 
-const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const DEFAULT_OUTPUT = join(homedir(), ".pi", "agent");
 
 const DEFAULT_WARN = (msg) => console.warn(`[pi-installer] ${msg}`);
 
-function isDirectory(p) {
+async function isDirectory(p) {
   try {
-    return statSync(p).isDirectory();
+    return (await stat(p)).isDirectory();
   } catch {
     return false;
   }
 }
 
-function isFile(p) {
+async function isFile(p) {
   try {
-    return statSync(p).isFile();
+    return (await stat(p)).isFile();
   } catch {
     return false;
   }
@@ -73,8 +74,8 @@ function isFile(p) {
  * @returns {{ agents: {name:string, filePath:string}[], skills: {skills:number, md:number, files:number, dir:string},
  *             warnings: string[], dryRun: boolean, agentsDir: string, skillsDir: string }}
  */
-export function installPi(options = {}) {
-  const root = options.root ?? REPO_ROOT;
+export async function installPi(options = {}) {
+  const root = options.root ?? PACKAGE_ROOT;
   const output = options.output ?? DEFAULT_OUTPUT;
   const dryRun = options.dryRun ?? false;
   const warnings = [];
@@ -83,7 +84,7 @@ export function installPi(options = {}) {
     (options.warn ?? DEFAULT_WARN)(msg);
   };
 
-  const tokenMap = loadTokenMap(root);
+  const tokenMap = await loadTokenMap(root);
   if (typeof tokenMap.version === "number" && tokenMap.version > CONTRACT_VERSION) {
     throw new Error(
       `token-map.json version ${tokenMap.version} is newer than the contract version ${CONTRACT_VERSION} this installer implements — upgrade agent-cortex`,
@@ -94,26 +95,28 @@ export function installPi(options = {}) {
   const agentsDir = join(output, "agents");
   const skillsDir = join(output, "skills");
 
-  const agents = installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn });
-  const skills = installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn });
+  const agents = await installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn });
+  const skills = await installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn });
 
   return { agents, skills, warnings, dryRun, agentsDir, skillsDir };
 }
 
 // ─── Agents ──────────────────────────────────────────────────────────────────
 
-function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn }) {
+async function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn }) {
   const written = [];
   const agentsSrc = join(root, "agents");
-  for (const entry of readdirSync(agentsSrc, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+  for (const entry of (await readdir(agentsSrc, { withFileTypes: true })).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )) {
     if (!entry.isDirectory()) continue; // skip generated *.agent.md flat files
     const dir = join(agentsSrc, entry.name);
-    if (!isFile(join(dir, "agent.md"))) continue; // not a composable agent dir
-    if (!isDirectory(join(dir, PI)) || !isFile(join(dir, PI, "frontmatter.json"))) {
+    if (!(await isFile(join(dir, "agent.md")))) continue; // not a composable agent dir
+    if (!(await isDirectory(join(dir, PI))) || !(await isFile(join(dir, PI, "frontmatter.json")))) {
       throw new Error(`agent "${entry.name}": composable directory without pi/frontmatter.json — define the pi harness or exclude the agent`);
     }
 
-    const fm = composeAgent(root, entry.name, PI, {
+    const fm = await composeAgent(root, entry.name, PI, {
       dropNullTools: true,
       pluginRoot,
       resolveRelativePaths: true,
@@ -123,8 +126,8 @@ function installAgents({ root, agentsDir, dryRun, pluginRoot, tokenMap, warn })
     const content = renderPiAgent(entry.name, fm, tools);
     const filePath = join(agentsDir, `${entry.name}.agent.md`);
     if (!dryRun) {
-      mkdirSync(agentsDir, { recursive: true });
-      writeFileSync(filePath, content);
+      await mkdir(agentsDir, { recursive: true });
+      await writeFile(filePath, content);
     }
     written.push({ name: entry.name, filePath });
   }
@@ -147,24 +150,24 @@ function renderPiAgent(name, fm, tools) {
 
 // ─── Skills ──────────────────────────────────────────────────────────────────
 
-function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn }) {
+async function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn }) {
   const skillsSrc = join(root, "skills");
-  if (!isDirectory(skillsSrc)) return { skills: 0, md: 0, files: 0, dir: skillsDir };
+  if (!(await isDirectory(skillsSrc))) return { skills: 0, md: 0, files: 0, dir: skillsDir };
 
   const transform = (content) =>
     substituteTokens(content, PI, tokenMap, { dropNullTools: true, pluginRoot, resolveRelativePaths: true, warn });
 
-  if (!dryRun) mkdirSync(skillsDir, { recursive: true });
+  if (!dryRun) await mkdir(skillsDir, { recursive: true });
   let skills = 0;
   let md = 0;
   let files = 0;
-  for (const group of readdirSync(skillsSrc).sort()) {
+  for (const group of (await readdir(skillsSrc)).sort()) {
     const groupDir = join(skillsSrc, group);
-    if (!isDirectory(groupDir)) continue;
-    for (const name of readdirSync(groupDir).sort()) {
-      if (!isFile(join(groupDir, name, "SKILL.md"))) continue;
+    if (!(await isDirectory(groupDir))) continue;
+    for (const name of (await readdir(groupDir)).sort()) {
+      if (!(await isFile(join(groupDir, name, "SKILL.md")))) continue;
       skills += 1;
-      const stats = copyTree(join(groupDir, name), join(skillsDir, group, name), transform, dryRun);
+      const stats = await copyTree(join(groupDir, name), join(skillsDir, group, name), transform, dryRun);
       md += stats.md;
       files += stats.files;
     }
@@ -173,24 +176,24 @@ function installSkills({ root, skillsDir, dryRun, pluginRoot, tokenMap, warn })
 }
 
 /** Recursively copy a tree; transform .md file contents, copy everything else verbatim. */
-function copyTree(src, dest, transform, dryRun) {
+async function copyTree(src, dest, transform, dryRun) {
   let md = 0;
   let files = 0;
-  const entries = readdirSync(src, { withFileTypes: true });
+  const entries = await readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     const from = join(src, entry.name);
     const to = join(dest, entry.name);
     if (entry.isDirectory()) {
-      const stats = copyTree(from, to, transform, dryRun);
+      const stats = await copyTree(from, to, transform, dryRun);
       md += stats.md;
       files += stats.files;
     } else if (entry.isFile()) {
       files += 1;
       if (entry.name.endsWith(".md")) md += 1;
       if (dryRun) continue;
-      mkdirSync(dest, { recursive: true });
-      if (entry.name.endsWith(".md")) writeFileSync(to, transform(readFileSync(from, "utf-8")));
-      else copyFileSync(from, to);
+      await mkdir(dest, { recursive: true });
+      if (entry.name.endsWith(".md")) await writeFile(to, transform(await readFile(from, "utf-8")));
+      else await copyFile(from, to);
     }
   }
   return { md, files };

package/docs/claude-hooks.md

@@ -2,8 +2,8 @@
 
 The pi extensions in `extensions/` were audited for Claude Code equivalents.
 Implemented ports live in `hooks/claude/hooks.json` (copied verbatim into the
-generated plugin as `claude/hooks.json`); support scripts live in
-`hooks/claude/scripts/` and are bundled into `claude/hooks/scripts/` by
+materialised plugin as its `hooks.json`); support scripts live in
+`hooks/claude/scripts/` and are bundled into the plugin's `hooks/scripts/` by
 `bin/installers/claude.mjs` (referenced from hooks.json via `$CLAUDE_PLUGIN_ROOT`).
 
 Claude Code's hook model differs from PI's: hooks are shell commands fed a JSON
@@ -100,7 +100,7 @@ for little signal. Rejected; Claude Code ships its own usage analytics
 ## `subagent/` → Reject (native)
 
 pi's `subagent` tool spawns isolated `pi --mode json` processes. Claude Code has
-native subagents — the plugin already ships `claude/agents/*.md` (including
+native subagents — the plugin already ships `~/.agent-cortex/claude/agents/*.md` (including
 `ralph`, `plan`, `strategy`, `ralph-plan`) executed via the built-in Agent/Task
 tools with per-session context isolation — so a hook-based workaround would be
 strictly worse.

package/extensions/agent-modes/README.md

@@ -34,8 +34,9 @@ contract:
 1. `{{SECTION:name}}` tokens are replaced with the agent's `pi/<name>.md`.
 2. `{{TOOL:key}}` / `{{PATH:key}}` tokens are substituted against the pi column
    of `token-map.json`, with the plugin root resolved from the actual extension
-   location. Tools without a PI equivalent (`ask_user`, `skill`) are omitted
-   from the tool set.
+   location. Tools map through that column (e.g. `ask_user` → `ask_questions`,
+   `skill` → `read`); a tool with a null mapping — any future one — is omitted
+   from the tool set with a warning.
 
 Flat `agents/*.agent.md` files are parsed as a fallback when an agent has no
 composable directory — they are generated output (scripts/build-copilot-agents.mjs)

package/extensions/agent-modes/discover.test.ts

@@ -137,8 +137,8 @@ describe("discoverAgents (composable source format)", () => {
 
     // {{TOOL:bash}} → bash.
     assert.match(plan.prompt, /Run with bash\./);
-    // {{TOOL:ask_user}} → null for pi — token dropped (dangling prose is the author's
-    // responsibility per token-map.README), not left as literal token syntax.
+    // {{TOOL:ask_user}} → ask_questions (pi's native structured-questions tool).
+    assert.match(plan.prompt, /Ask the user with ask_questions\./);
     assert.doesNotMatch(plan.prompt, /\{\{TOOL:ask_user\}\}/);
     // Relative {{PATH:...}} resolves against the actual package root (dir of agents/).
     assert.match(plan.prompt, new RegExp(`Read the plan skill at ${escapeRegExp(fx.dir)}/skills/workflow/plan/SKILL\\.md\\.`));
@@ -147,7 +147,7 @@ describe("discoverAgents (composable source format)", () => {
     assert.doesNotMatch(plan.prompt, /\{\{/);
   });
 
-  it("drops null-mapped tools (ask_user, skill) from the PI tool set", () => {
+  it("maps ask_user → ask_questions and skill → read into the PI tool set", () => {
     const fx = track(makeFixture());
     writeComposableAgent(fx, "plan", {
       frontmatter: {
@@ -159,8 +159,30 @@ describe("discoverAgents (composable source format)", () => {
 
     const agents = discoverAgents(fx.agentsDir, REAL_TOKEN_MAP);
     assert.equal(agents.length, 1);
-    // ask_user → null (omitted), skill → null (omitted), web_fetch → fetch_content.
-    assert.deepEqual(agents[0].tools, ["bash", "fetch_content"]);
+    // ask_user → ask_questions, skill → read (pi reads skill files), web_fetch → fetch_content.
+    assert.deepEqual(agents[0].tools, ["ask_questions", "bash", "fetch_content", "read"]);
+  });
+
+  it("warns and omits a tool whose pi mapping is null", () => {
+    const fx = track(makeFixture());
+    const NULL_MAP = {
+      tools: { ask_user: { copilot: "ask_user", claude: "AskUserQuestion", pi: null } },
+      paths: {},
+    } as TokenMap;
+    writeComposableAgent(fx, "plan", {
+      frontmatter: {
+        name: "agent-cortex:plan",
+        description: "Planner",
+        tools: ["ask_user", "bash"],
+      },
+    });
+
+    const agents = discoverAgents(fx.agentsDir, NULL_MAP);
+    assert.equal(agents.length, 1);
+    // With a null pi column the entry is omitted (and warned about), per the contract.
+    // (bash survives so the result is observable — an all-dropped list would be
+    // normalised to DEFAULT_TOOLS, which is "no restriction", not the omit result.)
+    assert.deepEqual(agents[0].tools, ["bash"]);
   });
 
   it("uses the built-in fallback map when token-map.json is unavailable", () => {
@@ -230,8 +252,9 @@ describe("loadTokenMap", () => {
   it("reads the real token-map.json at the package root", () => {
     assert.ok(REAL_TOKEN_MAP);
     assert.equal(typeof REAL_TOKEN_MAP?.tools?.bash?.pi, "string");
-    // ask_user has no PI equivalent per the contract — must stay null.
-    assert.equal(REAL_TOKEN_MAP?.tools?.ask_user?.pi, null);
+    // ask_user → ask_questions (pi's native structured-questions tool); skill → read.
+    assert.equal(REAL_TOKEN_MAP?.tools?.ask_user?.pi, "ask_questions");
+    assert.equal(REAL_TOKEN_MAP?.tools?.skill?.pi, "read");
     assert.ok(REAL_TOKEN_MAP?.paths?.agents_dir);
   });
 });

package/extensions/agent-modes/discover.ts

@@ -120,7 +120,7 @@ function prettifyId(id: string): string {
  * Translate a frontmatter tool list into PI tool names.
  *
  * With token-map.json: canonical keys are translated via the pi column; a null
- * mapping means PI has no equivalent (ask_user, skill) and the entry is omitted;
+ * mapping means PI has no equivalent for that tool and the entry is omitted;
  * a name that is not a canonical key passes through untouched (it may be a
  * native PI tool such as `fetch_content`). Without the map, the built-in
  * COPILOT_TO_PI fallback applies and unknown names pass through.

package/extensions/skill-stats/index.test.ts

@@ -331,17 +331,18 @@ describe("loadStore / saveStore", () => {
     const file = join(tmpDir, "test-store.json");
     const original = freshStore();
     original.totalTurns = 42;
+    const recentTs = new Date(Date.now() - 60 * 24 * 60 * 60 * 1000).toISOString();
     original.skills["test-skill"] = {
       loadedCount: 5,
       invokedCount: 2,
       readCount: 3,
-      lastUsed: "2026-06-07T12:00:00.000Z",
+      lastUsed: recentTs,
       byProject: {
         "/project/a": {
           loadedCount: 3,
           invokedCount: 1,
           readCount: 2,
-          lastUsed: "2026-06-07T12:00:00.000Z",
+          lastUsed: recentTs,
         },
       },
     };

package/lib/cli.mjs

@@ -5,9 +5,10 @@ const SUPPORTED_HARNESSES = ["copilot", "claude", "pi"];
 // malformed options surface as `optionError` on the parsed result; the CLI
 // prints them and exits 1.
 const INSTALL_OPTIONS = {
-  "--dry-run": { key: "dryRun" },
+  "--dry-run": { key: "dryRun", boolean: true },
   "--output": { key: "output" },
   "--plugin-root": { key: "pluginRoot" },
+  "--require-register": { key: "requireRegister", boolean: true },
 };
 
 export function parseArgs(argv) {
@@ -34,8 +35,8 @@ export function parseArgs(argv) {
       if (!spec) {
         return { command: "install", harness, optionError: `Unknown option "${arg}". Run "agent-cortex --help" for usage.` };
       }
-      if (spec.key === "dryRun") {
-        options.dryRun = true;
+      if (spec.boolean) {
+        options[spec.key] = true;
         continue;
       }
       if (inlineValue !== null) {
@@ -66,15 +67,26 @@ Commands:
   install <harness>   Install agent-cortex for a harness
                       Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}
                       Options (claude):
-                        (no --output)   Generate the plugin subtree AND register it
-                                        with Claude Code via the "claude plugin" CLI
-                                        (marketplace add → install → update) — requires
-                                        the plugin CLI (Claude Code v2+)
-                        --output <dir>  Write the plugin subtree to <dir> only — no
-                                        runtime registration (default: <package
-                                        root>/claude)
+                        (no --output)   Materialise the plugin into
+                                        ~/.agent-cortex/claude, write the
+                                        marketplace manifest at
+                                        ~/.agent-cortex/.claude-plugin/
+                                        marketplace.json, and register it with
+                                        Claude Code via the "claude plugin" CLI
+                                        (marketplace add → install → update,
+                                        idempotent by state: a re-run is the
+                                        update path, repeat install a no-op;
+                                        requires the plugin CLI, v2+)
+                        --output <dir>  Write the plugin subtree to <dir> only —
+                                        no marketplace manifest or registration
+                                        (default: ~/.agent-cortex/claude)
                         --dry-run       Print what would be generated/registered
                                         without writing
+                        --require-register
+                                        Fail the install when Claude Code
+                                        registration cannot run (missing CLI,
+                                        pre-v2 build); default warns and prints
+                                        the manual registration commands
                       Options (copilot):
                         --output <dir>   Write the flat *.agent.md files to <dir>
                                          (default: <package root>/agents — the dir

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaybeeuu/agent-cortex",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "Personal PI package with custom agents, skills, and extensions",
   "keywords": [
     "pi-package"
@@ -28,13 +28,13 @@
   },
   "scripts": {
     "build": "echo 'Build complete — no compilation needed for PI package'",
-    "lint": "pnpm typecheck",
+    "lint": "pnpm typecheck && pnpm check:sync",
+    "check:sync": "node scripts/check-no-sync.mjs",
     "test": "node --test test/*.test.mjs && pnpm -r test",
     "typecheck": "pnpm -r typecheck",
-    "build:claude": "node bin/agent-cortex.mjs install claude --output claude",
     "build:copilot": "node scripts/build-copilot-agents.mjs",
     "changeset": "changeset",
-    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:claude && pnpm build:copilot",
+    "version-packages": "changeset version && bash scripts/sync-plugin-version.sh && pnpm build:copilot",
     "publish-package": "TARBALL=$(pnpm pack | tail -n 1) && npm publish \"$TARBALL\" --provenance --access public",
     "release": "changeset publish",
     "postinstall": "bash scripts/install-instructions.sh"

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-cortex",
   "description": "Personal Copilot CLI plugin with custom agents and skills",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "author": {
     "name": "jaybeeuu"
   },

package/scripts/build-copilot-agents.mjs

@@ -27,4 +27,4 @@ import { installCopilot } from "../bin/installers/copilot.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 
-installCopilot({ root: ROOT, output: join(ROOT, "agents") });
+await installCopilot({ root: ROOT, output: join(ROOT, "agents") });

package/scripts/check-no-sync.mjs

@@ -0,0 +1,49 @@
+// Repo convention: never block the main thread — no `*Sync` functions
+// (fs/child_process/...) in tooling code. Runs via `pnpm lint` (CI) and
+// locally. Scans the toolchain and test dirs: bin/, scripts/, lib/, hooks/,
+// test/. Skill-owned scripts (skills/*/scripts) and extensions are separate
+// follow-up surfaces tracked outside this check.
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const SCAN_DIRS = ["bin", "scripts", "lib", "hooks", "test"];
+const EXTENSIONS = new Set([".mjs", ".js", ".ts"]);
+const SELF = "scripts/check-no-sync.mjs";
+
+const SYNC_CALL = /\b\w*Sync\s*\(/;
+
+/** Recursively collect files under dir, skipping this script and node_modules. */
+async function collect(dir) {
+  const out = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.name === "node_modules") continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await collect(full)));
+    else if (EXTENSIONS.has(e.name.slice(e.name.lastIndexOf(".")))) out.push(full);
+  }
+  return out;
+}
+
+const offenders = [];
+for (const dir of SCAN_DIRS) {
+  const abs = join(ROOT, dir);
+  for (const file of await collect(abs)) {
+    const rel = relative(ROOT, file);
+    if (rel === SELF) continue;
+    const src = await readFile(file, "utf-8");
+    const hits = src.split("\n").map((line, i) => ({ line: i + 1, text: line })).filter((l) => SYNC_CALL.test(l.text));
+    if (hits.length) offenders.push({ rel, hits });
+  }
+}
+
+if (offenders.length) {
+  console.error("✗ Never block the main thread — *Sync function calls found:");
+  for (const { rel, hits } of offenders) {
+    for (const { line, text } of hits) console.error(`  ${rel}:${line}: ${text.trim()}`);
+  }
+  process.exit(1);
+}
+console.log("✓ no *Sync calls in tooling code (bin/, scripts/, lib/, hooks/, test/)");

package/scripts/lib/compose-agent.mjs

@@ -29,9 +29,19 @@
 //
 // Zero dependencies so it runs on the CI Node (20) and local Node alike.
 
-import { readFileSync, existsSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
+/** True when a path exists (stat succeeds). */
+async function pathExists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // ─── Token substitution ──────────────────────────────────────────────────────
 
 const TOOL_RE = /\{\{TOOL:([^}]+)\}\}/g;
@@ -92,22 +102,30 @@ export function substituteTokens(content, harness, tokenMap, options = {}) {
  * @param {string} harness Harness id: "copilot" | "claude" | "pi"
  * @returns {{ name: string, description: string, tools: string[], model?: string, argumentHint?: string, body: string }}
  */
-export function composeAgent(root, name, harness, options = {}) {
+export async function composeAgent(root, name, harness, options = {}) {
   const { dropNullTools = false, pluginRoot, resolveRelativePaths = false, warn = noop } = options;
   const agentDir = join(root, "agents", name);
-  const frontmatter = parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
-  const tokenMap = loadTokenMap(root);
+  const frontmatter = await parseFrontmatter(join(agentDir, harness, "frontmatter.json"), name, harness);
+  const tokenMap = await loadTokenMap(root);
 
-  let body = readFileSync(join(agentDir, "agent.md"), "utf-8");
+  let body = await readFile(join(agentDir, "agent.md"), "utf-8");
 
-  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH tokens)
-  body = body.replace(/\{\{SECTION:([^}]+)\}\}/g, (_token, section) => {
+  // 1. {{SECTION:name}} → <harness>/<name>.md (may itself contain TOOL/PATH
+  //    tokens). Single pass over the original body — inserted section content
+  //    is never rescanned (same semantics as the sync replace()).
+  const sectionRe = /\{\{SECTION:([^}]+)\}\}/g;
+  let out = "";
+  let last = 0;
+  for (let m = sectionRe.exec(body); m; m = sectionRe.exec(body)) {
+    const section = m[1];
     const sectionPath = join(agentDir, harness, `${section}.md`);
-    if (!existsSync(sectionPath)) {
+    if (!(await pathExists(sectionPath))) {
       throw new Error(`agent "${name}": missing section "${section}" for harness "${harness}" (${sectionPath})`);
     }
-    return readFileSync(sectionPath, "utf-8").trim();
-  });
+    out += body.slice(last, m.index) + (await readFile(sectionPath, "utf-8")).trim();
+    last = m.index + m[0].length;
+  }
+  body = out + body.slice(last);
 
   // 2. + 3. TOOL/PATH substitution (contextualised for error messages)
   body = substituteTokens(body, harness, tokenMap, {
@@ -127,8 +145,8 @@ const REQUIRED_FIELDS = ["name", "description", "tools"];
 const KNOWN_OPTIONAL_FIELDS = ["model", "argumentHint"];
 
 /** Parse and schema-check a harness frontmatter.json (strict, per agents/README.md). */
-function parseFrontmatter(path, name, harness) {
-  const raw = readFileSync(path, "utf-8");
+async function parseFrontmatter(path, name, harness) {
+  const raw = await readFile(path, "utf-8");
   let fm;
   try {
     fm = JSON.parse(raw);
@@ -225,11 +243,11 @@ export function translateToolList(tools, tokenMap, harness, { warn = noop } = {}
 // ─── Token map ───────────────────────────────────────────────────────────────
 
 /** Load token-map.json from the package root; missing/incomplete maps hard-fail. */
-export function loadTokenMap(root) {
+export async function loadTokenMap(root) {
   const path = join(root, "token-map.json");
   let raw;
   try {
-    raw = readFileSync(path, "utf-8");
+    raw = await readFile(path, "utf-8");
   } catch {
     throw new Error(`missing ${path} — the composer requires token-map.json`);
   }

package/skills/engineering/grill-with-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: grill-with-docs
-description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when the user wants to stress-test a plan against their project's language and documented decisions: "grill my plan", "check this against our docs".
+description: "Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when the user wants to stress-test a plan against their project's language and documented decisions: \"grill my plan\", \"check this against our docs\"."
 ---
 
 # Grill With Docs

package/skills/workflow/hitl-collab/SKILL.md

@@ -80,7 +80,7 @@ Needs sign-off on the API contract change.
 - [ ] Contract change approved by reviewer
 ## Manual steps
 1. `pnpm install && pnpm test`
-2. `pnpm build:claude && git diff --stat claude/`
+2. `agent-cortex install claude --dry-run`   # materialiser smoke check (CI runs the full structural check)
 ## Verification checklist
 - [ ] Tests pass locally
 - [ ] Generated output up to date