portable-agent-layer 0.36.0 → 0.38.0

package/src/hooks/LoadContext.ts

@@ -39,7 +39,8 @@ try {
   // Determine agent target — controls which sections are skipped (loaded natively instead).
   let agent: AgentTarget = "claude";
   if (process.env.PAL_AGENT === "copilot") agent = "copilot";
-  else if (process.env.CURSOR_VERSION) agent = "cursor";
+  else if (process.env.PAL_AGENT === "cursor" || process.env.CURSOR_VERSION)
+    agent = "cursor";
   const reminder = buildSystemReminder({ agent });
   if (!reminder) process.exit(0);
 
@@ -61,12 +62,23 @@ try {
       "LoadContext",
       `Copilot session instructions written: ${context.length} chars`
     );
-  } else if (process.env.CURSOR_VERSION) {
+  } else if (process.env.PAL_AGENT === "cursor" || process.env.CURSOR_VERSION) {
     // Cursor: semi-static in ~/.cursor/rules/pal-context.mdc; inject AGENTS.md + dynamic here
     const agentsMd = buildClaudeMd();
     const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
     process.stdout.write(JSON.stringify({ additional_context: context }));
     logDebug("LoadContext", `Reminder injected: ${reminder.length} chars`);
+  } else if (process.env.PAL_AGENT === "codex") {
+    // Codex: AGENTS.md already loaded via symlink; inject only dynamic context
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "SessionStart",
+          additionalContext: reminder,
+        },
+      })
+    );
+    logDebug("LoadContext", `Codex reminder injected: ${reminder.length} chars`);
   } else {
     // Claude Code: raw text
     console.log(reminder);

package/src/hooks/PreCompactPersist.ts

@@ -11,17 +11,14 @@
  * is currently a Claude Code event.
  */
 
-import { writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { persistLastExchange } from "./handlers/persist-last-exchange";
 import { logDebug, logError } from "./lib/log";
-import { ensureDir, paths } from "./lib/paths";
+import { paths } from "./lib/paths";
 import { readStdinJSON } from "./lib/stdin";
-import {
-  extractContent,
-  extractLastAssistant,
-  extractLastUser,
-  readTranscriptFile,
-} from "./lib/transcript";
+import { readTranscriptFile } from "./lib/transcript";
 
 interface PreCompactInput {
   session_id?: string;
@@ -45,36 +42,31 @@ const main = async () => {
       logDebug("PreCompactPersist", "Transcript empty or unreadable");
       process.exit(0);
     }
+    const sessionId = input.session_id ?? "unknown";
+    const cwd = input.cwd ?? process.cwd();
 
-    const lastUser = extractContent(extractLastUser(messages));
-    const lastAssistant = extractContent(extractLastAssistant(messages));
-
-    if (!lastUser && !lastAssistant) {
-      logDebug("PreCompactPersist", "No user/assistant text found in transcript");
-      process.exit(0);
+    // Stop fires after every response and is authoritative. Skip if it already
+    // wrote latest.json for this session — PreCompact is a safety net only.
+    const latestPath = resolve(paths.state(), "last-exchange", "latest.json");
+    if (existsSync(latestPath)) {
+      try {
+        const latest = JSON.parse(await readFile(latestPath, "utf-8"));
+        if (latest?.sessionId === sessionId) {
+          logDebug(
+            "PreCompactPersist",
+            `Stop already persisted session ${sessionId} — skipping`
+          );
+          process.exit(0);
+        }
+      } catch {
+        /* unreadable — fall through and write */
+      }
     }
 
-    const sessionId = input.session_id || "unknown";
-    const payload = {
-      sessionId,
-      timestamp: new Date().toISOString(),
-      trigger: input.trigger ?? null,
-      customInstructions: input.custom_instructions || null,
-      userMessage: lastUser,
-      assistantMessage: lastAssistant,
-    };
-
-    const stateDir = ensureDir(resolve(paths.state(), "last-exchange"));
-    const sessionFile = resolve(stateDir, `${sessionId}.json`);
-    const latestFile = resolve(stateDir, "latest.json");
-    const json = `${JSON.stringify(payload, null, 2)}\n`;
-
-    writeFileSync(sessionFile, json, "utf-8");
-    writeFileSync(latestFile, json, "utf-8");
-
+    persistLastExchange(messages, sessionId, cwd);
     logDebug(
       "PreCompactPersist",
-      `Saved last exchange (user=${lastUser.length}ch, assistant=${lastAssistant.length}ch) for session ${sessionId}`
+      `Persisted exchange before compaction for session ${sessionId}`
     );
   } catch (err) {
     logError("PreCompactPersist", err);
@@ -83,4 +75,4 @@ const main = async () => {
   process.exit(0);
 };
 
-main();
+await main();

package/src/hooks/SecurityValidator.ts

@@ -6,47 +6,69 @@
  */
 
 import { blockResponse } from "./lib/agent";
-import { checkBashCommand, checkFilePath, WARN_COMMANDS } from "./lib/security";
+import { checkBashCommand, checkFilePath } from "./lib/security";
 import { readStdinJSON } from "./lib/stdin";
 
+// preToolUse shape (Claude Code + Cursor + Codex)
 interface ToolUseInput {
   tool_name: string;
+  hook_event_name?: string; // Codex includes this in all hook inputs
   tool_input: {
     command?: string;
     file_path?: string;
   };
 }
 
-try {
-  const input = await readStdinJSON<ToolUseInput>();
-  if (!input) process.exit(0);
+// beforeShellExecution shape (Cursor only) — flat, no tool_name wrapper
+interface ShellExecInput {
+  command: string;
+  sandbox?: boolean;
+}
 
-  const { tool_name, tool_input } = input;
+type SecurityInput = ToolUseInput | ShellExecInput;
 
-  // Normalize tool names: Claude uses "Bash", Cursor uses "Shell"
-  const isBash = tool_name === "Bash" || tool_name === "Shell";
-  const isFileWrite = tool_name === "Write" || tool_name === "Edit";
+function isShellExec(input: SecurityInput): input is ShellExecInput {
+  return !("tool_name" in input) && "command" in input;
+}
+
+try {
+  const input = await readStdinJSON<SecurityInput>();
+  if (!input) process.exit(0);
 
-  // Check shell commands
-  if (isBash && tool_input.command) {
-    const reason = checkBashCommand(tool_input.command);
+  if (isShellExec(input)) {
+    // beforeShellExecution — command is always a shell command
+    const reason = checkBashCommand(input.command);
     if (reason) {
       process.stdout.write(blockResponse(`Blocked: ${reason}`));
-      process.exit(0);
     }
+    process.exit(0);
+  }
+
+  const hookEventName = input.hook_event_name;
+
+  // preToolUse — Claude: "Bash", Cursor: "Shell", Codex: "shell"
+  const isBash =
+    input.tool_name === "Bash" ||
+    input.tool_name === "Shell" ||
+    input.tool_name === "shell";
+  const isFileWrite =
+    input.tool_name === "Write" ||
+    input.tool_name === "Edit" ||
+    input.tool_name === "write_file" ||
+    input.tool_name === "apply_patch";
 
-    for (const pattern of WARN_COMMANDS) {
-      if (pattern.test(tool_input.command)) {
-        break;
-      }
+  if (isBash && input.tool_input.command) {
+    const reason = checkBashCommand(input.tool_input.command);
+    if (reason) {
+      process.stdout.write(blockResponse(`Blocked: ${reason}`, hookEventName));
+      process.exit(0);
     }
   }
 
-  // Check file path operations
-  if (isFileWrite && tool_input.file_path) {
-    const fileReason = checkFilePath(tool_input.file_path);
-    if (fileReason) {
-      process.stdout.write(blockResponse(fileReason));
+  if (isFileWrite && input.tool_input.file_path) {
+    const reason = checkFilePath(input.tool_input.file_path);
+    if (reason) {
+      process.stdout.write(blockResponse(reason, hookEventName));
       process.exit(0);
     }
   }

package/src/hooks/StopOrchestrator.ts

@@ -7,7 +7,7 @@
  */
 
 import { checkReadmeSync } from "./handlers/readme-sync";
-import { isCursor } from "./lib/agent";
+import { isCodex, isCursor } from "./lib/agent";
 import { logError } from "./lib/log";
 import { readStdinJSON } from "./lib/stdin";
 import { runStopHandlers } from "./lib/stop";
@@ -26,6 +26,9 @@ try {
     if (isCursor()) {
       // Cursor stop hook: followup_message auto-sends to the agent
       process.stdout.write(JSON.stringify({ followup_message: decision.reason }));
+    } else if (isCodex()) {
+      // Codex stop hook: additionalContext re-queues as next prompt
+      process.stdout.write(JSON.stringify({ additionalContext: decision.reason }));
     } else {
       // Claude Code: block decision
       process.stdout.write(JSON.stringify(decision));

package/src/hooks/UserPromptOrchestrator.ts

@@ -16,15 +16,17 @@ import { readStdinJSON } from "./lib/stdin";
 interface PromptSubmitInput {
   prompt: string;
   session_id?: string;
+  conversation_id?: string; // Cursor sends this instead of session_id
 }
 
 const input = await readStdinJSON<PromptSubmitInput>();
 logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)}`);
 if (!input?.prompt) process.exit(0);
 
+const sessionId = input.session_id ?? input.conversation_id;
 const results = await Promise.allSettled([
-  captureRating(input.prompt, input.session_id),
-  captureSessionName(input.prompt, input.session_id ?? ""),
+  captureRating(input.prompt, sessionId),
+  captureSessionName(input.prompt, sessionId ?? ""),
   injectRetrieval(input.prompt),
 ]);
 

package/src/hooks/handlers/auto-graduate.ts

@@ -77,12 +77,12 @@ function alreadyPromoted(state: GraduationState, pattern: string): boolean {
   return state.graduated.some((g) => g.pattern === pattern);
 }
 
-export interface AutoGraduateOptions {
+interface AutoGraduateOptions {
   /** Bypass the 24h TTL guard. State + content dedup still apply. */
   force?: boolean;
 }
 
-export interface AutoGraduateResult {
+interface AutoGraduateResult {
   ranAnalysis: boolean;
   candidatesAtFloor: number;
   promoted: number;

package/src/hooks/handlers/backup.ts

@@ -4,7 +4,7 @@
  * is older than 7 days, or if no backup exists yet.
  */
 
-import { readdirSync, statSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
 import { resolve } from "node:path";
 import { exportZip, timestamp } from "../lib/export";
 import { logDebug } from "../lib/log";
@@ -16,14 +16,14 @@ export async function autoBackup(): Promise<void> {
   const backupDir = paths.backups();
 
   // Check most recent backup
-  const existing = readdirSync(backupDir)
+  const existing = (await readdir(backupDir))
     .filter((f) => f.startsWith("pal-backup-") && f.endsWith(".zip"))
     .sort()
     .reverse();
 
   if (existing.length > 0) {
     const latestPath = resolve(backupDir, existing[0]);
-    const latestMtime = statSync(latestPath).mtimeMs;
+    const latestMtime = (await stat(latestPath)).mtimeMs;
     if (Date.now() - latestMtime < BACKUP_INTERVAL_MS) {
       logDebug("backup", "Skipping — last backup is less than 7 days old");
       return;

package/src/hooks/handlers/failure.ts

@@ -7,7 +7,7 @@
  * Analysis is left to the human or the graduation pipeline, not auto-generated.
  */
 
-import { writeFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { stringify } from "../lib/frontmatter";
 import { ensureDir, paths } from "../lib/paths";
@@ -31,7 +31,8 @@ export async function captureFailure(
   context: string,
   transcript: string,
   detailedContext?: string,
-  principle?: string
+  principle?: string,
+  cwd?: string
 ): Promise<void> {
   const messages = parseMessages(transcript);
 
@@ -57,6 +58,7 @@ export async function captureFailure(
     slug,
   };
   if (principle) meta.principle = principle;
+  if (cwd) meta.cwd = cwd;
 
   const body = [
     "## What Happened",
@@ -69,5 +71,5 @@ export async function captureFailure(
     conversationSummary || "*(unavailable)*",
   ].join("\n");
 
-  writeFileSync(resolve(dir, "capture.md"), stringify(meta, body), "utf-8");
+  await writeFile(resolve(dir, "capture.md"), stringify(meta, body), "utf-8");
 }

package/src/hooks/handlers/inject-retrieval.ts

@@ -7,6 +7,7 @@
  * timeout produces empty output, never blocks the prompt.
  */
 
+import { isCodex, isCursor } from "../lib/agent";
 import { logDebug, logError } from "../lib/log";
 import { runRetrieval } from "../lib/retrieval";
 import { ensureIndex } from "../lib/retrieval-index";
@@ -29,9 +30,10 @@ function withTimeout<T>(work: () => T, ms: number): Promise<T | null> {
   });
 }
 
-export async function injectRetrieval(prompt: string): Promise<void> {
-  if (!prompt?.trim()) return;
-  if (!isEnabled("learningInjection")) return;
+/** Returns the retrieval reminder string, or null if nothing to inject. @lintignore dynamically imported by opencode plugin */
+export async function getRetrievalReminder(prompt: string): Promise<string | null> {
+  if (!prompt?.trim()) return null;
+  if (!isEnabled("learningInjection")) return null;
 
   const result = await withTimeout(() => {
     const index = ensureIndex();
@@ -39,12 +41,33 @@ export async function injectRetrieval(prompt: string): Promise<void> {
     return runRetrieval(prompt, index, process.cwd());
   }, TIMEOUT_MS);
 
-  if (!result?.reminder) return;
+  if (!result?.reminder) return null;
 
   logDebug(
     "inject-retrieval",
-    `injected ${result.matches.length} matches; top score=${result.matches[0]?.confidence.toFixed(3)}`
+    `${result.matches.length} matches; top score=${result.matches[0]?.confidence.toFixed(3)}`
   );
 
-  process.stdout.write(`${result.reminder}\n`);
+  return result.reminder;
+}
+
+/** Write retrieval reminder to stdout in the correct format for the current agent.
+ *  Claude Code: plain text. Cursor: { additional_context }. Codex: hookSpecificOutput JSON. */
+export async function injectRetrieval(prompt: string): Promise<void> {
+  const reminder = await getRetrievalReminder(prompt);
+  if (!reminder) return;
+  if (isCursor()) {
+    process.stdout.write(JSON.stringify({ additional_context: reminder }));
+  } else if (isCodex()) {
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "UserPromptSubmit",
+          additionalContext: reminder,
+        },
+      })
+    );
+  } else {
+    process.stdout.write(`${reminder}\n`);
+  }
 }

package/src/hooks/handlers/persist-last-exchange.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared handler: persist the last user/assistant exchange on every Stop and PreCompact.
+ *
+ * Writes two outputs:
+ *  1. last-exchange/{sessionId}.json + last-exchange/latest.json
+ *     → read by CompactRecover to re-inject after compaction
+ *  2. last-handoff.json keyed by cwd
+ *     → read by loadHandoff() to surface "Pick Up Where You Left Off"
+ *
+ * Always overwrites — Stop is the source of truth for both. The LEARN-phase
+ * handoff-note.ts tool may also write to last-handoff.json; whichever runs last wins,
+ * but raw exchange is sufficient for continuity and costs nothing.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { logDebug, logError } from "../lib/log";
+import { ensureDir, paths } from "../lib/paths";
+import { extractContent, extractLastAssistant, extractLastUser } from "../lib/transcript";
+import { detectStatus } from "../lib/work-tracking";
+
+type ParsedMessage = { role: string; content: unknown };
+
+export function persistLastExchange(
+  messages: ParsedMessage[],
+  sessionId: string,
+  cwd: string = process.cwd()
+): void {
+  try {
+    const lastUser = extractContent(extractLastUser(messages));
+    const lastAssistant = extractContent(extractLastAssistant(messages));
+    if (!lastUser && !lastAssistant) return;
+
+    // 1. Write last-exchange files for CompactRecover
+    const stateDir = ensureDir(resolve(paths.state(), "last-exchange"));
+    const payload = {
+      sessionId,
+      timestamp: new Date().toISOString(),
+      trigger: null,
+      customInstructions: null,
+      userMessage: lastUser,
+      assistantMessage: lastAssistant,
+    };
+    const json = `${JSON.stringify(payload, null, 2)}\n`;
+    writeFileSync(resolve(stateDir, `${sessionId}.json`), json, "utf-8");
+    writeFileSync(resolve(stateDir, "latest.json"), json, "utf-8");
+
+    // 2. Write last-handoff.json for "Pick Up Where You Left Off"
+    const handoffPath = resolve(paths.state(), "last-handoff.json");
+    const existing: Record<string, unknown> = existsSync(handoffPath)
+      ? JSON.parse(readFileSync(handoffPath, "utf-8"))
+      : {};
+    const title = (lastUser.slice(0, 80).replace(/\n/g, " ") || "Session").trim();
+    const handoff = [
+      lastUser ? `Last user message:\n${lastUser.slice(0, 500)}` : "",
+      lastAssistant ? `\nLast assistant response:\n${lastAssistant.slice(0, 500)}` : "",
+    ]
+      .filter(Boolean)
+      .join("");
+    existing[cwd] = {
+      timestamp: new Date().toISOString(),
+      title,
+      status: detectStatus(lastAssistant),
+      handoff,
+      artifacts: [],
+    };
+    writeFileSync(handoffPath, JSON.stringify(existing, null, 2), "utf-8");
+
+    logDebug(
+      "persist-last-exchange",
+      `Persisted exchange for session ${sessionId} (user=${lastUser.length}ch, assistant=${lastAssistant.length}ch)`
+    );
+  } catch (err) {
+    logError("persist-last-exchange", err);
+  }
+}

package/src/hooks/handlers/rating.ts

@@ -48,7 +48,7 @@ export function parseExplicitRating(
   prompt: string
 ): { rating: number; comment?: string } | null {
   const trimmed = prompt.trim();
-  const match = trimmed.match(/^(10|[1-9])(?:\s*[-:,]\s*|\s+)?(.*)$/);
+  const match = new RegExp(/^(10|[1-9])(?:\s*[-:,]\s*|\s+)?(.*)$/).exec(trimmed);
   if (!match) return null;
 
   const rating = parseInt(match[1], 10);
@@ -271,6 +271,7 @@ function handleRating(
           principle,
           responsePreview,
           userPreview,
+          cwd: process.cwd(),
           ts: now(),
         },
         null,

package/src/hooks/handlers/readme-sync.ts

@@ -33,7 +33,7 @@ function hasDocumentableChanges(): boolean {
   }
 }
 
-export interface ReadmeSyncDecision {
+interface ReadmeSyncDecision {
   decision?: "block";
   reason?: string;
 }
@@ -50,9 +50,10 @@ export function checkReadmeSync(): ReadmeSyncDecision {
 
   if (!result.ok) {
     logDebug("readme-sync", `README out of sync: ${result.issues.join("; ")}`);
+    const issueList = result.issues.map((i) => `- ${i}`).join("\n");
     return {
       decision: "block",
-      reason: `README.md is out of date. Please update it before finishing:\n${result.issues.map((i) => `- ${i}`).join("\n")}`,
+      reason: `README.md is out of date. Please update it before finishing:\n${issueList}`,
     };
   }
 

package/src/hooks/handlers/session-intelligence.ts

@@ -7,13 +7,13 @@
  * Relationship notes → written in ALGORITHM LEARN phase via relationship-note.ts
  * Handoff notes     → written in ALGORITHM LEARN phase via handoff-note.ts
  *
- * Replaces: work-learning.ts (still exists but is bypassed).
  */
 
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { unlink, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { stringify } from "../lib/frontmatter";
-import { inference } from "../lib/inference";
+import { hasApiKey, inference } from "../lib/inference";
 import { categorizeLearning } from "../lib/learning-category";
 import { logDebug, logError } from "../lib/log";
 import { ensureDir, paths } from "../lib/paths";
@@ -27,7 +27,7 @@ import {
 } from "../lib/transcript";
 import { appendProjectHistory, detectStatus } from "../lib/work-tracking";
 
-// ── Dedup tracking (same as work-learning) ──
+// ── Dedup tracking ──
 
 interface CaptureEntry {
   filepath: string;
@@ -138,7 +138,7 @@ export async function captureSessionIntelligence(
   }
 
   // Skip if no API key
-  if (!process.env.PAL_ANTHROPIC_API_KEY) {
+  if (!hasApiKey()) {
     logDebug("session-intelligence", "Skipped: no PAL_ANTHROPIC_API_KEY");
     return;
   }
@@ -161,6 +161,7 @@ export async function captureSessionIntelligence(
 
   // Single Haiku call
   logDebug("session-intelligence", "Calling inference...");
+  const numberedMessages = userWindow.map((m, i) => `${i + 1}. ${m}`).join("\n");
   let output: IntelligenceOutput | null = null;
   try {
     const result = await inference({
@@ -175,7 +176,7 @@ export async function captureSessionIntelligence(
           ? "4. handoff: what remains unfinished — decisions made so far, next steps, blockers (2-4 sentences)"
           : "4. handoff: empty string (session completed)",
       ].join("\n"),
-      user: `User messages:\n${userWindow.map((m, i) => `${i + 1}. ${m}`).join("\n")}\n\nLast AI response:\n${assistantWindow}`,
+      user: `User messages:\n${numberedMessages}\n\nLast AI response:\n${assistantWindow}`,
       maxTokens: 350,
       timeout: 15000,
       jsonSchema: INTELLIGENCE_SCHEMA,
@@ -224,7 +225,7 @@ export async function captureSessionIntelligence(
     const prev = getPreviousCapture(sessionId);
     if (prev?.filepath && existsSync(prev.filepath)) {
       try {
-        unlinkSync(prev.filepath);
+        await unlink(prev.filepath);
       } catch {
         /* ignore */
       }
@@ -232,7 +233,7 @@ export async function captureSessionIntelligence(
   }
 
   const filepath = resolve(dir, filename);
-  writeFileSync(filepath, content, "utf-8");
+  await writeFile(filepath, content, "utf-8");
 
   // Append to per-project history
   appendProjectHistory(process.cwd(), {

package/src/hooks/handlers/session-name.ts

@@ -10,7 +10,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { inference } from "../lib/inference";
+import { hasApiKey, inference } from "../lib/inference";
 import { logDebug, logError } from "../lib/log";
 import {
   extractFallbackName,
@@ -42,7 +42,7 @@ export async function captureSessionName(
   logDebug("session-name", `Named from prompt: "${name}"`);
 
   // Spawn detached background process to upgrade with Haiku inference
-  if (!process.env.PAL_ANTHROPIC_API_KEY) return;
+  if (!hasApiKey()) return;
   try {
     const promptB64 = Buffer.from(message.slice(0, 800)).toString("base64");
     const child = spawn(

package/src/hooks/handlers/synthesis.ts

@@ -3,7 +3,8 @@
  * Imports synthesize logic directly — no subprocess needed.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { logDebug } from "../lib/log";
 import { paths } from "../lib/paths";
@@ -16,7 +17,9 @@ export async function runSynthesis(): Promise<void> {
   // Check 24h guard
   if (existsSync(statePath)) {
     try {
-      const data = JSON.parse(readFileSync(statePath, "utf-8")) as { timestamp: string };
+      const data = JSON.parse(await readFile(statePath, "utf-8")) as {
+        timestamp: string;
+      };
       if (Date.now() - new Date(data.timestamp).getTime() < SYNTHESIS_TTL_MS) {
         logDebug("synthesis", "Skipped — last synthesis < 24h ago");
         return;

package/src/hooks/handlers/update-counts.ts

@@ -4,7 +4,8 @@
  * scanning directories and JSONL files.
  */
 
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { assets, ensureDir, paths } from "../lib/paths";
 
@@ -147,5 +148,5 @@ function getCounts(): Counts {
 export async function updateCounts(): Promise<void> {
   const counts = getCounts();
   const countsPath = resolve(ensureDir(paths.state()), "counts.json");
-  writeFileSync(countsPath, JSON.stringify(counts, null, 2), "utf-8");
+  await writeFile(countsPath, JSON.stringify(counts, null, 2), "utf-8");
 }