portable-agent-layer 0.75.1 → 0.76.1

package/src/hooks/lib/work-tracking.ts

@@ -4,8 +4,9 @@
  */
 
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
+import { defaultSlug, readAllProjects, resolveProjectFromCwd } from "./projects";
 
 // ── Session Records ──────────────────────────────────────────────
 
@@ -146,25 +147,29 @@ interface ProjectHistoryEntry {
   insights: string;
 }
 
-/** Convert a cwd path to a filesystem-safe slug (last directory segment) */
-function cwdToSlug(cwd: string): string {
-  const normalized = cwd.replaceAll("\\", "/").replace(/\/+$/, "");
-  return normalized.split("/").pop() || "unknown";
+/**
+ * A directory under `memory/projects/` is what `list`, `resume` and the export
+ * read as a project, so only a registered one may own a folder there. Writer and
+ * readers share this resolver: keying them apart is what filed a project's
+ * history under its parent directory's name.
+ */
+function historyFileFor(cwd: string): string {
+  const project = resolveProjectFromCwd(cwd, readAllProjects());
+  return project
+    ? resolve(paths.projectHistory(), project.name, "history.jsonl")
+    : resolve(paths.unboundHistory(), `${defaultSlug(cwd)}.jsonl`);
 }
 
-/** Append a learning entry to the project's history.jsonl */
+/** Append a learning entry to the history file owning this cwd */
 export function appendProjectHistory(cwd: string, entry: ProjectHistoryEntry): void {
-  const slug = cwdToSlug(cwd);
-  const dir = ensureDir(resolve(paths.projectHistory(), slug));
-  const historyPath = resolve(dir, "history.jsonl");
-  const line = `${JSON.stringify(entry)}\n`;
-  appendFileSync(historyPath, line, "utf-8");
+  const historyPath = historyFileFor(cwd);
+  ensureDir(dirname(historyPath));
+  appendFileSync(historyPath, `${JSON.stringify(entry)}\n`, "utf-8");
 }
 
-/** Read the project history for a given cwd */
+/** Read the session history for a given cwd */
 export function readProjectHistory(cwd: string, limit = 15): ProjectHistoryEntry[] {
-  const slug = cwdToSlug(cwd);
-  const historyPath = resolve(paths.projectHistory(), slug, "history.jsonl");
+  const historyPath = historyFileFor(cwd);
   if (!existsSync(historyPath)) return [];
   try {
     const lines = readFileSync(historyPath, "utf-8").trim().split("\n").filter(Boolean);

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: {

package/src/tools/agent/handoff-note.ts

@@ -6,8 +6,8 @@
  * Written by Claude in-session — no inference call needed.
  *
  * Usage:
- *   bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains + next steps"
- *   bun ~/.pal/tools/handoff-note.ts --done   # mark completed, suppress next-session injection
+ *   pal cli handoff-note --title "what we were doing" --text "what remains + next steps"
+ *   pal cli handoff-note --done   # mark completed, suppress next-session injection
  */
 
 import { writeFileSync } from "node:fs";
@@ -20,13 +20,14 @@ import {
   recordNote,
   statusOf,
 } from "../lib/handoff-note";
+import { scriptArgs } from "../lib/script-args";
 
 const HELP = `
 HandoffNote — Write a handoff note for the current project
 
 Usage:
-  bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains"
-  bun ~/.pal/tools/handoff-note.ts --done    # mark session completed
+  pal cli handoff-note --title "what we were doing" --text "what remains"
+  pal cli handoff-note --done    # mark session completed
 
 Arguments:
   --title   Brief title of what was being worked on (5-10 words)
@@ -44,9 +45,9 @@ function saveNote(note: NoteInput): void {
   emit.receipt(file, { status: statusOf(note), entries: Object.keys(store).length });
 }
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       title: { type: "string" },
       text: { type: "string" },

package/src/tools/agent/project.ts

@@ -6,27 +6,27 @@
  * Frontmatter holds operational state; body holds ISA spec sections.
  *
  * Usage:
- *   bun ~/.pal/tools/project.ts list
- *   bun ~/.pal/tools/project.ts create [name] [--path PATH] [--objectives "..."] [--serves goal|revenue|fun]
- *   bun ~/.pal/tools/project.ts serves <name> <goal|revenue|fun> [note]
- *   bun ~/.pal/tools/project.ts resume <name>
- *   bun ~/.pal/tools/project.ts complete | archive | pause | unpause <name>
- *   bun ~/.pal/tools/project.ts add-next <name> "text"
- *   bun ~/.pal/tools/project.ts add-blocker <name> "text"
- *   bun ~/.pal/tools/project.ts add-decision <name> "decision" "rationale"
- *   bun ~/.pal/tools/project.ts add-handoff <name> "text"
- *   bun ~/.pal/tools/project.ts rm-next | rm-blocker <name> <index>
- *   bun ~/.pal/tools/project.ts update-section <name> <section> "content"
- *   bun ~/.pal/tools/project.ts criteria <name>
- *   bun ~/.pal/tools/project.ts isa-init <name>
- *   bun ~/.pal/tools/project.ts migrate
+ *   pal cli project list
+ *   pal cli project create [name] [--path PATH] [--objectives "..."] [--serves goal|revenue|fun]
+ *   pal cli project serves <name> <goal|revenue|fun> [note]
+ *   pal cli project resume <name>
+ *   pal cli project complete | archive | pause | unpause <name>
+ *   pal cli project add-next <name> "text"
+ *   pal cli project add-blocker <name> "text"
+ *   pal cli project add-decision <name> "decision" "rationale"
+ *   pal cli project add-handoff <name> "text"
+ *   pal cli project rm-next | rm-blocker <name> <index>
+ *   pal cli project update-section <name> <section> "content"
+ *   pal cli project criteria <name>
+ *   pal cli project isa-init <name>
+ *   pal cli project migrate
  */
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { writeBinding } from "../../hooks/lib/bindings";
-import { paths } from "../../hooks/lib/paths";
+import { paths, toPath } from "../../hooks/lib/paths";
 import {
   defaultSlug,
   deleteProject,
@@ -55,6 +55,7 @@ import {
   selectIscs,
   taskSlug,
 } from "../lib/project-isc";
+import { scriptArgs } from "../lib/script-args";
 
 function now(): string {
   return new Date().toISOString();
@@ -106,7 +107,7 @@ function cmdCreate(args: string[]): void {
     allowPositionals: true,
   });
 
-  const path = resolve(values.path ?? process.cwd());
+  const path = toPath(values.path ?? process.cwd());
   const name = (values.name ?? positionals[0] ?? defaultSlug(path)).trim();
 
   if (!/^[a-z0-9_-]+$/.test(name)) {
@@ -271,7 +272,7 @@ function addHandoff(name: string, text: string): void {
 function cmdSetPath(args: string[]): void {
   const [name, ...rest] = args;
   if (!name || rest.length === 0) fail("Usage: set-path <name> <new-path>");
-  const newPath = resolve(rest.join(" ").trim());
+  const newPath = toPath(rest.join(" ").trim());
   const p = requireProject(name);
   writeBinding(p.name, newPath);
   p.updated = now();
@@ -693,8 +694,8 @@ Commands:
 `);
 }
 
-function run(): void {
-  const [cmd, ...rest] = Bun.argv.slice(2);
+export function run(argv: string[] = scriptArgs()): void {
+  const [cmd, ...rest] = argv;
   if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
     help();
     return;
@@ -810,7 +811,7 @@ function run(): void {
       cmdRm(rest);
       return;
     default:
-      fail(`Unknown command "${cmd}". Run 'project.ts help' for usage.`);
+      fail(`Unknown command "${cmd}". Run 'pal cli project help' for usage.`);
   }
 }
 

package/src/tools/agent/relationship-note.ts

@@ -6,9 +6,9 @@
  * the user (O, W) and session diary entries (--b).
  *
  * Usage:
- *   bun ~/.pal/tools/relationship-note.ts --o "User prefers X" --confidence 0.80
- *   bun ~/.pal/tools/relationship-note.ts --w "User is building X in TypeScript"
- *   bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
+ *   pal cli relationship-note --o "User prefers X" --confidence 0.80
+ *   pal cli relationship-note --w "User is building X in TypeScript"
+ *   pal cli relationship-note --b "Debugged the cache split logic"
  *
  * Note types:
  *   --o   Opinion/behavioral observation about the user (requires --confidence)
@@ -22,14 +22,15 @@ import { parseArgs } from "node:util";
 import { appendNotes } from "../../hooks/lib/relationship";
 import { emit } from "../lib/emit";
 import { notesFromFlags } from "../lib/note-flags";
+import { scriptArgs } from "../lib/script-args";
 
 const HELP = `
 RelationshipNote — Append W/O/Session entries to today's relationship log
 
 Usage:
-  bun ~/.pal/tools/relationship-note.ts --o "User prefers X" --confidence 0.80
-  bun ~/.pal/tools/relationship-note.ts --w "User is building X in TypeScript"
-  bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
+  pal cli relationship-note --o "User prefers X" --confidence 0.80
+  pal cli relationship-note --w "User is building X in TypeScript"
+  pal cli relationship-note --b "Debugged the cache split logic"
 
 Flags:
   --o TEXT          Opinion/behavioral observation about the user
@@ -42,9 +43,9 @@ Multiple flags may be combined in one call. At least one of --o, --w, --b is req
 Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
 `;
 
-if (import.meta.main) {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       o: { type: "string", multiple: true },
       w: { type: "string", multiple: true },
@@ -68,3 +69,5 @@ if (import.meta.main) {
   const { file, written } = appendNotes(result.notes);
   emit.receipt(file, { written, deduped: result.notes.length - written });
 }
+
+if (import.meta.main) run();

package/src/tools/agent/synthesize.ts

@@ -7,7 +7,7 @@
  * reads and formats with behavioral guidance.
  *
  * Usage:
- *   bun ~/.pal/tools/synthesize.ts [--days 7] [--force]
+ *   pal cli synthesize [--days 7] [--force]
  *
  * Guards: skips if last synthesis was < 24h ago (unless --force).
  * Output: ~/.pal/memory/state/synthesis.json
@@ -17,6 +17,7 @@ import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { ensureDir, paths } from "../../hooks/lib/paths";
+import { scriptArgs } from "../lib/script-args";
 import { readJsonl } from "../lib/self-model";
 
 // ── Config ──
@@ -303,9 +304,9 @@ export function synthesize(days: number): SynthesisState {
 
 // ── CLI ──
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       days: { type: "string", default: "7" },
       force: { type: "boolean" },

package/src/tools/agent/thread.ts

@@ -6,13 +6,14 @@
  * Stored in memory/state/threads.jsonl as structured records.
  *
  * Usage:
- *   bun ~/.pal/tools/thread.ts --add --title "..." [--context "..."]
- *   bun ~/.pal/tools/thread.ts --resolve --id <id>
- *   bun ~/.pal/tools/thread.ts --list [--all]
+ *   pal cli thread --add --title "..." [--context "..."]
+ *   pal cli thread --resolve --id <id>
+ *   pal cli thread --list [--all]
  */
 
 import { parseArgs } from "node:util";
 import { emit } from "../lib/emit";
+import { scriptArgs } from "../lib/script-args";
 import {
   addThread,
   readThreads,
@@ -59,9 +60,9 @@ function markResolved(id: string | undefined) {
   emit.receipt(file, { id, status: "resolved", title: resolution.thread.title });
 }
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       add: { type: "boolean" },
       resolve: { type: "boolean" },

package/src/tools/agent/wisdom-frame.ts

@@ -20,6 +20,7 @@ import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
+import { scriptArgs } from "../lib/script-args";
 
 // ── Types ──
 
@@ -192,9 +193,9 @@ ${antiPatternEntry}
 
 // ── CLI ──
 
-function run() {
+export function run(argv: string[] = scriptArgs()) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       domain: { type: "string", short: "d" },
       observation: { type: "string", short: "o" },

package/src/tools/lib/script-args.ts

@@ -0,0 +1,4 @@
+/** The arguments a spawned tool was given: argv leads with the runtime and the script path. */
+export function scriptArgs(argv: string[] = process.argv): string[] {
+  return argv.slice(2);
+}

package/src/tools/lib/skill-doctor.ts

@@ -12,7 +12,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, extname, relative, resolve } from "node:path";
-import { palHome } from "../../hooks/lib/paths";
+import { palHome, toPath } from "../../hooks/lib/paths";
 import { declaredTriggers } from "../../hooks/lib/skill-triggers";
 
 type Level = "pass" | "warn" | "error";
@@ -449,7 +449,7 @@ export function formatReport(r: DoctorReport): string {
  * report names the directory the caller meant rather than a guess.
  */
 export function resolveSkillDir(arg: string): string {
-  const asPath = resolve(arg);
+  const asPath = toPath(arg);
   if (existsSync(resolve(asPath, "SKILL.md"))) return asPath;
   const byName = resolve(palHome(), "skills", arg);
   if (existsSync(resolve(byName, "SKILL.md"))) return byName;

package/src/tools/self-model.ts

@@ -9,7 +9,7 @@
  * ~/.pal/memory/self-model/current.md that is injected at session start.
  *
  * Usage:
- *   bun ~/.pal/tools/self-model.ts [--days 30] [--force] [--dry-run]
+ *   bun src/tools/self-model.ts [--days 30] [--force] [--dry-run]
  *
  * Every decision this makes lives in ./lib/self-model.ts, where the suite
  * reaches it directly; what stays here is paths, inference and the writes.

package/src/tools/skill-doctor.ts

@@ -15,7 +15,7 @@ import { formatReport, lintSkill, resolveSkillDir } from "./lib/skill-doctor";
 if (import.meta.main) {
   const arg = process.argv[2];
   if (!arg) {
-    console.error("Usage: bun src/tools/skill-doctor.ts <skill-dir-or-name>");
+    console.error("Usage: pal cli skill doctor <skill-dir-or-name>");
     process.exit(2);
   }
   const report = lintSkill(resolveSkillDir(arg));

package/src/tools/subagent-doctor.ts

@@ -13,7 +13,7 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
-import { assets, palHome } from "../hooks/lib/paths";
+import { assets, namesAPath, palHome, toPath } from "../hooks/lib/paths";
 
 type Level = "pass" | "warn" | "error";
 
@@ -396,16 +396,16 @@ export function formatSubagentReport(r: SubagentReport): string {
 
 /** Resolve a doctor argument to a subagent .md path (a path, or a name in the store). */
 export function resolveSubagentFile(arg: string): string {
-  if (arg.endsWith(".md") && existsSync(resolve(arg))) return resolve(arg);
-  const direct = resolve(arg);
+  const direct = toPath(arg);
   if (existsSync(direct) && direct.endsWith(".md")) return direct;
+  if (namesAPath(arg)) return direct.endsWith(".md") ? direct : `${direct}.md`;
   return resolve(palHome(), "agents", arg.endsWith(".md") ? arg : `${arg}.md`);
 }
 
 if (import.meta.main) {
   const arg = process.argv[2];
   if (!arg) {
-    console.error("Usage: bun src/tools/subagent-doctor.ts <file-or-name>");
+    console.error("Usage: pal cli subagent doctor <file-or-name>");
     process.exit(2);
   }
   const report = lintSubagent(resolveSubagentFile(arg));