portable-agent-layer 0.75.0 → 0.76.0

package/assets/templates/rules.codex.rules

@@ -61,4 +61,69 @@ prefix_rule(
         "node ~/.pal/skills/consulting-report/tools/generate-pdf.ts ./report",
     ],
 )
+
+prefix_rule(
+    pattern = ["pal", "cli", "project"],
+    decision = "allow",
+    justification = "PAL project state commands are part of the installed PAL workflow",
+    match = [
+        "pal cli project resume portable-agent-layer",
+        "pal cli project list-isc portable-agent-layer",
+        "pal cli project add-next portable-agent-layer note",
+    ],
+    not_match = [
+        "pal cli install",
+    ],
+)
+
+prefix_rule(
+    pattern = ["pal", "cli", "algorithm-reflect"],
+    decision = "allow",
+    justification = "PAL Algorithm reflection logging is part of the installed PAL workflow",
+    match = [
+        "pal cli algorithm-reflect --task work --criteria 1 --passed 1 --failed 0 --sentiment 8",
+    ],
+    not_match = [
+        "pal cli project list",
+    ],
+)
+
+prefix_rule(
+    pattern = [
+        "pal",
+        "cli",
+        [
+            "algorithm-synthesize",
+            "analyze",
+            "handoff-note",
+            "relationship-note",
+            "synthesize",
+            "thread",
+            "wisdom-frame",
+        ],
+    ],
+    decision = "allow",
+    justification = "PAL installed agent tools are safe to run without repeated approval",
+    match = [
+        "pal cli thread --list",
+        "pal cli wisdom-frame --help",
+    ],
+    not_match = [
+        "pal cli project list",
+        "pal cli uninstall",
+    ],
+)
+
+prefix_rule(
+    pattern = ["pal", "cli", "skill", "run"],
+    decision = "allow",
+    justification = "A skill's own tools ship with PAL and are safe to run without repeated approval",
+    match = [
+        "pal cli skill run presentation build ./deck",
+        "pal cli skill run consulting-report generate-pdf.mjs ./report",
+    ],
+    not_match = [
+        "pal cli skill link my-skill",
+    ],
+)
 # END PAL MANAGED CODEX RULES

package/assets/templates/settings.claude.json

@@ -34,7 +34,17 @@
       "Bash(rtk gain *)",
       "Bash(bun ~/.pal/skills/*/tools/*.ts *)",
       "Bash(bun ~/.pal/tools/*.ts *)",
-      "Bash(node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts *)"
+      "Bash(node --experimental-strip-types ~/.pal/skills/consulting-report/tools/generate-pdf.ts *)",
+      "Bash(pal cli skill run *)",
+      "Bash(pal cli algorithm-reflect *)",
+      "Bash(pal cli algorithm-synthesize *)",
+      "Bash(pal cli analyze *)",
+      "Bash(pal cli handoff-note *)",
+      "Bash(pal cli project *)",
+      "Bash(pal cli relationship-note *)",
+      "Bash(pal cli synthesize *)",
+      "Bash(pal cli thread *)",
+      "Bash(pal cli wisdom-frame *)"
     ]
   },
   "skillOverrides": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/builtin-tools.ts

@@ -0,0 +1,30 @@
+/**
+ * PAL's own agent tools, surfaced as `pal cli <verb>`.
+ *
+ * Instruction text names the verb rather than `bun ~/.pal/tools/<tool>.ts`, so
+ * no shell has to expand a tilde — which cmd.exe never does and PowerShell
+ * passes through literally — and a tool can move without breaking every doc
+ * that calls it. Each entry imports lazily, so an unused verb costs nothing.
+ */
+const BUILTIN_TOOLS = {
+  "algorithm-reflect": () => import("../tools/agent/algorithm-reflect"),
+  "algorithm-synthesize": () => import("../tools/agent/algorithm-synthesize"),
+  analyze: () => import("../tools/agent/analyze"),
+  "handoff-note": () => import("../tools/agent/handoff-note"),
+  project: () => import("../tools/agent/project"),
+  "relationship-note": () => import("../tools/agent/relationship-note"),
+  synthesize: () => import("../tools/agent/synthesize"),
+  thread: () => import("../tools/agent/thread"),
+  "wisdom-frame": () => import("../tools/agent/wisdom-frame"),
+} satisfies Record<string, () => Promise<{ run: (argv: string[]) => unknown }>>;
+
+export const builtinToolVerbs = Object.keys(BUILTIN_TOOLS).sort();
+
+/** Dispatch a built-in verb; false means the command belongs to the main switch. */
+export async function runBuiltinTool(command: string, args: string[]): Promise<boolean> {
+  const load = BUILTIN_TOOLS[command as keyof typeof BUILTIN_TOOLS];
+  if (!load) return false;
+  const { run } = await load();
+  await run(args);
+  return true;
+}

package/src/cli/index.ts

@@ -18,6 +18,8 @@
  *   usage                             Summarize token usage and cost
  *   ledger <sub> [filters]            Query the action ledger (log · show · stats)
  *   server start|stop|restart|status  The control room, a local page over ~/.pal
+ *   <tool> [args]                     Run a built-in agent tool (project, thread, analyze, …)
+ *   skill run <skill> <tool> [-- args]  Run a skill's own tool by name, not by path
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name|--all>         Evaluate one skill, or every installed skill, against the authoring best practices
  *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
@@ -47,10 +49,12 @@ import {
 import { inference, previewInferenceRoute } from "../hooks/lib/inference";
 import { DEBUG_LOG_MAX_ROTATED, logDebug } from "../hooks/lib/log";
 import { ensureRegistered, writeRegistryEntry } from "../hooks/lib/machine";
-import { palHome, palPkg, paths, platform } from "../hooks/lib/paths";
+import { palHome, palPkg, paths, platform, toPath } from "../hooks/lib/paths";
 import { auditBindings, describeBindingIssue } from "../hooks/lib/projects";
 import { telosStatus } from "../hooks/lib/telos-topics";
+import { findBinaryOnPath } from "../hooks/lib/which";
 import { log } from "../targets/lib";
+import { builtinToolVerbs, runBuiltinTool } from "./builtin-tools";
 import { checkPendingMigrations } from "./migrate";
 
 const allArgs = process.argv.slice(2);
@@ -184,6 +188,7 @@ async function session(sessionArgs: string[]) {
 // ── CLI dispatcher ──
 
 async function runCli(command: string | undefined, args: string[]) {
+  if (command && (await runBuiltinTool(command, args))) return;
   switch (command) {
     case "init":
       await init(args);
@@ -219,11 +224,6 @@ async function runCli(command: string | undefined, args: string[]) {
       runMigrate(args);
       break;
     }
-    case "analyze": {
-      const { run: runAnalyze } = await import("../tools/agent/analyze");
-      await runAnalyze(args);
-      break;
-    }
     case "usage": {
       const { usage } = await import("../tools/token-cost");
       usage();
@@ -338,7 +338,8 @@ function showHelp() {
     pal cli status                          Show PAL configuration
     pal cli doctor [--probe-inference]      Check prerequisites and health (--probe fires real inference per route)
     pal cli migrate [--list] [--dry-run]    Run pending data migrations
-    pal cli analyze [--actionable]          Learning analysis: ratings, failure patterns, graduation candidates
+    pal cli <tool> [args]                   Run a built-in agent tool ('<tool> --help' for its flags):
+                                            ${builtinToolVerbs.join(" · ")}
     pal cli usage                           Summarize token usage and cost
     pal cli actor [label <name>]            Show or rename this actor (who caused a record)
     pal cli machine [label <name>]          Show or rename this install (where it was written)
@@ -349,6 +350,7 @@ function showHelp() {
     pal cli ledger <sub> [filters]          Query the action ledger (log · show · stats)
                                             e.g. ledger log --project X --since 7d
     pal cli server start|stop|restart|status  The control room: a local page to open before a terminal
+    pal cli skill run <skill> <tool> [-- args]  Run ~/.pal/skills/<skill>/tools/<tool> by name
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name|--all>       Evaluate one skill, or every installed skill
     pal cli skill author-model              Print the flagship model that authors skills for the active agent
@@ -833,6 +835,12 @@ function doctor(silent = false): DoctorResult {
     console.log("");
     log.info("Prerequisites");
     ok(`Bun ${bun.version}`);
+    const palBin = findBinaryOnPath("pal");
+    palBin
+      ? ok(`pal on PATH — ${palBin}`)
+      : fail(
+          "pal — not on PATH; skills and docs invoke tools as 'pal cli ...', which will not resolve. Install globally: bun add -g portable-agent-layer"
+        );
     const node = checkNode();
     if (!node.available) {
       warn(
@@ -1361,7 +1369,7 @@ async function exportState(args: string[]) {
 
   const dryRun = args.includes("--dry-run");
   const pathArg = args.find((a) => !a.startsWith("-"));
-  const resolvedArg = pathArg ? resolve(pathArg) : null;
+  const resolvedArg = pathArg ? toPath(pathArg) : null;
   const argIsDir =
     resolvedArg !== null &&
     existsSync(resolvedArg) &&
@@ -1425,7 +1433,7 @@ async function importState(args: string[]) {
 
   let zipPath: string;
 
-  const resolvedArg = pathArg ? resolve(pathArg) : null;
+  const resolvedArg = pathArg ? toPath(pathArg) : null;
   const argIsDir =
     resolvedArg !== null &&
     existsSync(resolvedArg) &&

package/src/cli/knowledge.ts

@@ -23,6 +23,7 @@
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import * as clack from "@clack/prompts";
+import { toPath } from "../hooks/lib/paths";
 import { buildGraph, resolveSlug, stats, traverse } from "../tools/knowledge/graph";
 import {
   type CompanyInput,
@@ -553,7 +554,7 @@ interface IngestPayload {
 }
 
 async function readIngestInput(file: string | undefined): Promise<string | null> {
-  if (file) return readFileSync(file, "utf-8");
+  if (file) return readFileSync(toPath(file), "utf-8");
   if (process.stdin.isTTY) return null;
   return await Bun.stdin.text();
 }

package/src/cli/skill.ts

@@ -8,15 +8,25 @@
  *   pal cli skill doctor --all    Evaluate every installed skill, one line each.
  *   pal cli skill author-model    Print the flagship model configured to author
  *                                 skills for the active agent (empty if none).
+ *   pal cli skill run <skill> <tool> [-- args]
+ *                                 Run ~/.pal/skills/<skill>/tools/<tool>, so a
+ *                                 SKILL.md can name the tool instead of a path
+ *                                 with a tilde no Windows shell expands.
  */
 
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import { getActiveAgent } from "../hooks/lib/agent";
 import { flagshipAuthorModel } from "../hooks/lib/models";
 import { palHome } from "../hooks/lib/paths";
 import { linkPersonalSkill, log } from "../targets/lib";
-import { formatReport, formatSummary, lintSkill } from "../tools/lib/skill-doctor";
+import {
+  formatReport,
+  formatSummary,
+  lintSkill,
+  resolveSkillDir,
+} from "../tools/lib/skill-doctor";
 
 /** Entry names under ~/.pal/skills/, sorted; dangling links included. */
 function skillEntries(dir: string): string[] {
@@ -59,9 +69,51 @@ function doctorAll(): number {
   return failing > 0 ? 1 : 0;
 }
 
+/** One plain path segment — the containment guarantee for `skill run`. */
+function isPlainSegment(part: string): boolean {
+  return (
+    part.length > 0 && part !== "." && part !== ".." && !new RegExp(/[/\\\0]/).test(part)
+  );
+}
+
+/** Playwright tools ship compiled as .mjs and need Node; everything else is Bun. */
+function runtimeFor(file: string): string {
+  return file.endsWith(".mjs") ? "node" : "bun";
+}
+
+function toolFileName(tool: string): string {
+  return new RegExp(/\.[a-z]+$/).test(tool) ? tool : `${tool}.ts`;
+}
+
+function runSkillTool(skill: string, tool: string, toolArgs: string[]): number {
+  if (!isPlainSegment(skill) || !isPlainSegment(tool)) {
+    log.error("Skill and tool must be plain names — no path separators, no '..'");
+    return 1;
+  }
+  const file = toolFileName(tool);
+  const path = resolve(palHome(), "skills", skill, "tools", file);
+  if (!existsSync(path)) {
+    log.error(`No tool '${file}' in skill '${skill}' — looked in ${path}`);
+    return 1;
+  }
+  const { status } = spawnSync(runtimeFor(file), [path, ...toolArgs], {
+    stdio: "inherit",
+  });
+  return status ?? 1;
+}
+
 export async function runSkill(args: string[]): Promise<number> {
   const [sub, name] = args;
 
+  if (sub === "run") {
+    const [, skill, tool, ...rest] = args;
+    if (!skill || !tool) {
+      log.error("Usage: pal cli skill run <skill> <tool> [-- args]");
+      return 1;
+    }
+    return runSkillTool(skill, tool, rest[0] === "--" ? rest.slice(1) : rest);
+  }
+
   if (sub === "author-model") {
     const model = flagshipAuthorModel(getActiveAgent());
     if (model) console.log(model);
@@ -71,10 +123,10 @@ export async function runSkill(args: string[]): Promise<number> {
   if (sub === "doctor") {
     if (name === "--all") return doctorAll();
     if (!name) {
-      log.error("Usage: pal cli skill doctor <name|--all>");
+      log.error("Usage: pal cli skill doctor <skill-dir-or-name|--all>");
       return 1;
     }
-    const report = lintSkill(resolve(palHome(), "skills", name));
+    const report = lintSkill(resolveSkillDir(name));
     console.log(formatReport(report));
     return report.errors > 0 ? 1 : 0;
   }
@@ -104,6 +156,6 @@ export async function runSkill(args: string[]): Promise<number> {
     }
   }
 
-  log.error("Usage: pal cli skill <link|doctor|author-model> [name|--all]");
+  log.error("Usage: pal cli skill <run|link|doctor|author-model> [name|--all]");
   return 1;
 }

package/src/cli/subagent.ts

@@ -40,7 +40,7 @@ export async function runSubagent(args: string[]): Promise<number> {
 
   if (sub === "doctor") {
     if (!name) {
-      log.error("Usage: pal cli subagent doctor <name>");
+      log.error("Usage: pal cli subagent doctor <file-or-name>");
       return 1;
     }
     const report = lintSubagent(resolveSubagentFile(name));

package/src/hooks/lib/agent.ts

@@ -9,9 +9,13 @@
  * Detection reads PAL_AGENT first (set in-process by
  * `src/targets/opencode/plugin.ts`), then the host's own environment, and only
  * then the `--agent=` flag the install templates in `assets/templates/*` put
- * on the hook command line. See declaredAgent for why that order.
+ * on the hook command line. See declaredAgent for why that order. When nothing
+ * declares an agent at all, getActiveAgent falls back to the agent CLIs found
+ * on PATH rather than assuming claude.
  */
 
+import { findBinaryOnPath } from "./which";
+
 export type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode" | "vscode";
 
 const KNOWN_AGENTS: ReadonlySet<AgentType> = new Set([
@@ -109,9 +113,36 @@ export function declaredAgent(): AgentType | undefined {
   return agentFromRuntimeEnv() ?? flag;
 }
 
-/** Which agent's conventions to follow. Assumes "claude" when undeclared. */
+/**
+ * The CLI each agent spawns for inference, in the order inference.ts routes
+ * them. vscode is absent because it has no CLI of its own — it runs Claude's.
+ */
+const AGENT_BINARIES: ReadonlyArray<readonly [AgentType, string]> = [
+  ["claude", "claude"],
+  ["codex", "codex"],
+  ["opencode", "opencode"],
+  ["copilot", "copilot"],
+  ["cursor", "cursor-agent"],
+];
+
+/**
+ * Which agent this machine actually has, for the case where nothing declared
+ * one — a plain terminal running `pal cli`, a cron child, a detached spawn.
+ * Assuming claude there names an agent that may not be installed, which routes
+ * inference to a binary that isn't on PATH and reports a host that isn't there.
+ */
+function agentFromInstalledBinary(): AgentType | undefined {
+  return AGENT_BINARIES.find(([, binary]) => findBinaryOnPath(binary) !== null)?.[0];
+}
+
+/**
+ * Which agent's conventions to follow.
+ *
+ * A declaration always wins; claude remains the last resort so a machine with
+ * no agent CLI at all behaves as it always has.
+ */
 export function getActiveAgent(): AgentType {
-  return declaredAgent() ?? "claude";
+  return declaredAgent() ?? agentFromInstalledBinary() ?? "claude";
 }
 
 export const isClaude = () => getActiveAgent() === "claude";

package/src/hooks/lib/bindings.ts

@@ -20,7 +20,7 @@
 import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { palHome } from "./paths";
+import { palHome, toPath } from "./paths";
 
 /** Project name → absolute path on this machine. */
 export type Bindings = Record<string, string>;
@@ -105,7 +105,7 @@ export function writeBinding(
   home: string = palHome()
 ): void {
   const bindings = readBindings(home);
-  bindings[project] = resolve(path);
+  bindings[project] = toPath(path);
   writeBindings(bindings, home);
 }
 

package/src/hooks/lib/context.ts

@@ -4,14 +4,13 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { loadAnalyzeNudge } from "./analyze-nudge";
 import { readLearnings } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
-import { paths } from "./paths";
+import { paths, toPath } from "./paths";
 import { loadActiveProjectsContext } from "./projects";
 import { loadRecentNotes } from "./relationship";
 import { loadFailurePatterns } from "./semi-static";
@@ -24,11 +23,10 @@ function loadStartupFiles(): string {
   const files = settings.startupFiles();
   if (files.length === 0) return "";
 
-  const home = homedir();
   const sections: string[] = [];
 
   for (const file of files) {
-    const resolved = file.replace("~", home);
+    const resolved = toPath(file);
     if (!existsSync(resolved)) continue;
     try {
       const content = readFileSync(resolved, "utf-8").trim();

package/src/hooks/lib/paths.ts

@@ -2,13 +2,53 @@ import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 
+/**
+ * Turn a path string that came from outside — argv, a flag, an env override, a
+ * persisted record — into a real absolute path.
+ *
+ * "~" is a shell feature, not a filesystem one: bash and zsh expand it before a
+ * process starts, cmd.exe has no such feature, and PowerShell hands it to native
+ * commands untouched. So node:path has nothing for it (`resolve("~/x")` yields
+ * `<cwd>/~/x`) and every caller that skips this function is a Windows bug.
+ *
+ * Only the leading segment counts. `~user` throws instead of resolving, because
+ * it needs a passwd lookup and quietly reading it as a relative directory is the
+ * exact failure this replaces.
+ */
+export function toPath(input: string, base: string = process.cwd()): string {
+  if (input === "~") return homedir();
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return resolve(homedir(), input.slice(2));
+  }
+  if (input.startsWith("~")) {
+    throw new Error(`Home-relative paths for another user are not supported: ${input}`);
+  }
+  return resolve(base, input);
+}
+
+/**
+ * Whether a string names a location rather than a bare identifier. A verb that
+ * accepts either `my-skill` or `~/skills/my-skill` has to tell them apart before
+ * it looks the argument up in a store — appending a tilde path to a store
+ * directory yields a path that can never exist.
+ */
+export function namesAPath(input: string): boolean {
+  return input.startsWith("~") || input.includes("/") || input.includes("\\");
+}
+
+/** An env override names a path the same way a flag does, so it gets the same treatment. */
+function envPath(name: string, fallback: string): string {
+  const override = process.env[name];
+  return override ? toPath(override) : fallback;
+}
+
 /**
  * Root of the PAL package (engine code + shipped assets).
  * In repo mode: the repo root.
  * In package mode: the global node_modules package directory.
  */
 export function palPkg(): string {
-  return process.env.PAL_PKG || resolve(import.meta.dir, "..", "..", "..");
+  return envPath("PAL_PKG", resolve(import.meta.dir, "..", "..", ".."));
 }
 
 /**
@@ -17,7 +57,7 @@ export function palPkg(): string {
  * Power users who want memory/telos versioned in a repo can override via PAL_HOME.
  */
 export function palHome(): string {
-  return process.env.PAL_HOME || resolve(homedir(), ".pal");
+  return envPath("PAL_HOME", resolve(homedir(), ".pal"));
 }
 
 /** Ensure a directory exists, creating it recursively if needed */
@@ -68,12 +108,12 @@ export const paths = {
 // Platform directories (env override or cross-platform defaults)
 const h = homedir();
 export const platform = {
-  claudeDir: () => process.env.PAL_CLAUDE_DIR || resolve(h, ".claude"),
-  opencodeDir: () => process.env.PAL_OPENCODE_DIR || resolve(h, ".config", "opencode"),
-  cursorDir: () => process.env.PAL_CURSOR_DIR || resolve(h, ".cursor"),
-  copilotDir: () => process.env.PAL_COPILOT_DIR || resolve(h, ".copilot"),
-  codexDir: () => process.env.PAL_CODEX_DIR || resolve(h, ".codex"),
-  agentsDir: () => process.env.PAL_AGENTS_DIR || resolve(h, ".agents"),
+  claudeDir: () => envPath("PAL_CLAUDE_DIR", resolve(h, ".claude")),
+  opencodeDir: () => envPath("PAL_OPENCODE_DIR", resolve(h, ".config", "opencode")),
+  cursorDir: () => envPath("PAL_CURSOR_DIR", resolve(h, ".cursor")),
+  copilotDir: () => envPath("PAL_COPILOT_DIR", resolve(h, ".copilot")),
+  codexDir: () => envPath("PAL_CODEX_DIR", resolve(h, ".codex")),
+  agentsDir: () => envPath("PAL_AGENTS_DIR", resolve(h, ".agents")),
 } as const;
 
 // Engine/asset paths (in PAL_PKG / repo root)

package/src/hooks/lib/projects.ts

@@ -459,7 +459,7 @@ export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
   if (showHint) {
     if (visible.length > 0) lines.push("");
     lines.push(
-      `💡 \`${projectRoot}\` looks like a project but isn't registered. If substantive work starts here, suggest registering it via \`bun ~/.pal/tools/project.ts create\`.`
+      `💡 \`${projectRoot}\` looks like a project but isn't registered. If substantive work starts here, suggest registering it via \`pal cli project create\`.`
     );
   }
 

package/src/hooks/lib/which.ts

@@ -9,9 +9,26 @@
  *    names — passing the full `.cmd`/`.exe` path bypasses that fragility.
  */
 
-import { accessSync, constants, existsSync } from "node:fs";
+import { accessSync, constants, statSync } from "node:fs";
 import { delimiter, resolve as resolvePath } from "node:path";
 
+/**
+ * A directory carries the execute bit as "traversable", so X_OK alone accepts
+ * a folder that happens to share a CLI's name. statSync follows symlinks, so a
+ * linked binary still resolves. Windows has no executable bit — being a file
+ * under a PATHEXT extension is all it can offer.
+ */
+function isExecutableFile(candidate: string): boolean {
+  try {
+    if (!statSync(candidate).isFile()) return false;
+    if (process.platform === "win32") return true;
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** Resolve a binary on PATH to its full absolute path, or null if absent. */
 export function findBinaryOnPath(name: string): string | null {
   const PATH = process.env.PATH;
@@ -24,17 +41,7 @@ export function findBinaryOnPath(name: string): string | null {
     if (!dir) continue;
     for (const ext of exts) {
       const candidate = resolvePath(dir, name + ext);
-      try {
-        if (process.platform === "win32") {
-          // Windows has no executable bit — existence in PATHEXT is enough.
-          if (existsSync(candidate)) return candidate;
-        } else {
-          accessSync(candidate, constants.X_OK);
-          return candidate;
-        }
-      } catch {
-        /* not here — try next */
-      }
+      if (isExecutableFile(candidate)) return candidate;
     }
   }
   return null;

package/src/tools/agent/algorithm-reflect.ts

@@ -18,6 +18,7 @@ import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
 import { buildReflection, intOr, reflectionLine } from "../lib/algorithm-reflect";
 import { emit } from "../lib/emit";
+import { scriptArgs } from "../lib/script-args";
 
 const HELP = `
 AlgorithmReflect — Log algorithm performance after LEARN phase
@@ -45,9 +46,9 @@ function reflectionsPath(): string {
   return paths.reflectionsFile();
 }
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       task: { type: "string" },
       criteria: { type: "string" },

package/src/tools/agent/algorithm-synthesize.ts

@@ -20,6 +20,7 @@
 import { parseArgs } from "node:util";
 import { readReflections } from "../../hooks/lib/learning-store";
 import { paths } from "../../hooks/lib/paths";
+import { scriptArgs } from "../lib/script-args";
 
 /** Algorithm areas a Q2 idea can target, mapped to ALGORITHM.md structure. */
 const BUCKETS: { key: string; label: string; patterns: RegExp }[] = [
@@ -202,9 +203,9 @@ export function formatAlgorithmReport(s: AlgorithmSynthesis): string {
   return lines.join("\n");
 }
 
-if (import.meta.main) {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: process.argv.slice(2),
+    args: argv,
     options: {
       since: { type: "string" },
       json: { type: "boolean", default: false },
@@ -216,3 +217,5 @@ if (import.meta.main) {
     values.json ? JSON.stringify(result, null, 2) : formatAlgorithmReport(result)
   );
 }
+
+if (import.meta.main) run();

package/src/tools/agent/analyze.ts

@@ -14,6 +14,7 @@ import { parseArgs } from "node:util";
 import { writeLastAnalyzeDate } from "../../hooks/lib/analyze-nudge";
 import { analyze } from "../../hooks/lib/graduation";
 import { reportLines } from "../lib/analyze-report";
+import { scriptArgs } from "../lib/script-args";
 
 const HELP = `
   PAL Learning Analysis — unified graduation + ratings report
@@ -36,7 +37,7 @@ const HELP = `
   Usage: pal cli analyze [--actionable]
 `;
 
-export async function run(argv: string[] = Bun.argv.slice(2)) {
+export async function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
     args: argv,
     options: {