portable-agent-layer 0.76.0 → 0.76.1

package/package.json

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

package/src/cli/migrate.ts

@@ -12,16 +12,22 @@
 
 import {
   existsSync,
+  mkdirSync,
   readdirSync,
   readFileSync,
   renameSync,
+  rmdirSync,
+  unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
+import { readBindings } from "../hooks/lib/bindings";
+import { mergeJsonlLines } from "../hooks/lib/import-merge";
 import { palHome, paths } from "../hooks/lib/paths";
 import {
   legacyJsonToProgress,
   type ProjectProgress,
+  projectPathOnThisMachine,
   readAllProjects,
   readProject,
   writeProject,
@@ -516,12 +522,140 @@ const v5AttributionKeys: Migration = {
   },
 };
 
+// ── v6-history-slugs: history filed by cwd name → its owning project ──
+
+/**
+ * Session history used to be keyed on the last segment of the cwd, so a session
+ * in an unregistered directory minted a project-shaped folder, and a project
+ * checked out under a differently-named directory had its history filed under
+ * that directory instead. Both now route through `historyFileFor`; this brings
+ * the records already on disk onto the same rule.
+ */
+interface StrandedHistory {
+  slug: string;
+  file: string;
+  owner: string | null;
+  parked: boolean;
+}
+
+function orphanHistoryFolders(): { slug: string; file: string }[] {
+  const base = paths.projectHistory();
+  if (!existsSync(base)) return [];
+  const out: { slug: string; file: string }[] = [];
+  for (const slug of readdirSync(base)) {
+    const dir = resolve(base, slug);
+    const file = resolve(dir, "history.jsonl");
+    if (!existsSync(file) || existsSync(resolve(dir, "ISA.md"))) continue;
+    out.push({ slug, file });
+  }
+  return out;
+}
+
+function parkedHistoryFiles(): { slug: string; file: string }[] {
+  const base = paths.unboundHistory();
+  if (!existsSync(base)) return [];
+  return readdirSync(base)
+    .filter((f) => f.endsWith(".jsonl"))
+    .map((f) => ({ slug: f.slice(0, -".jsonl".length), file: resolve(base, f) }));
+}
+
+/** The project checked out in a directory of this name, when exactly one is. */
+function projectOwningDirectoryNamed(slug: string): string | null {
+  const bindings = readBindings();
+  const owners = readAllProjects().filter((p) => {
+    const path = projectPathOnThisMachine(p, bindings);
+    return path !== null && basename(path) === slug;
+  });
+  return owners.length === 1 ? owners[0].name : null;
+}
+
+/** Orphans always move; parked history moves only once its project appears. */
+function strandedHistory(): StrandedHistory[] {
+  const out: StrandedHistory[] = [];
+  for (const { slug, file } of orphanHistoryFolders()) {
+    out.push({ slug, file, owner: projectOwningDirectoryNamed(slug), parked: false });
+  }
+  for (const { slug, file } of parkedHistoryFiles()) {
+    const owner = projectOwningDirectoryNamed(slug);
+    if (owner) out.push({ slug, file, owner, parked: true });
+  }
+  return out;
+}
+
+function destinationFor(item: StrandedHistory): string {
+  return item.owner
+    ? resolve(paths.projectHistory(), item.owner, "history.jsonl")
+    : resolve(paths.unboundHistory(), `${item.slug}.jsonl`);
+}
+
+/** Union both sides so a destination that already has history keeps it. */
+function foldHistoryInto(target: string, source: string): number {
+  const local = existsSync(target) ? readFileSync(target, "utf-8") : "";
+  const { text, added } = mergeJsonlLines(local, readFileSync(source, "utf-8"));
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, text, "utf-8");
+  return added;
+}
+
+function discardEmptyFolder(dir: string): void {
+  try {
+    if (readdirSync(dir).length === 0) rmdirSync(dir);
+  } catch {
+    /* left in place — never worth failing a migration over */
+  }
+}
+
+const v6HistorySlugs: Migration = {
+  id: "v6-history-slugs",
+  description: "Re-file session history keyed on a cwd name onto its owning project",
+
+  check() {
+    const stranded = strandedHistory();
+    return {
+      pending: stranded.length > 0,
+      detail:
+        stranded.length > 0
+          ? `${stranded.length} history file(s) filed under a directory name`
+          : undefined,
+    };
+  },
+
+  run(dryRun = false): MigrationResult {
+    const results: string[] = [];
+    let migrated = 0;
+    let skipped = 0;
+
+    for (const item of strandedHistory()) {
+      const target = destinationFor(item);
+      const where = item.owner ? `project ${item.owner}` : "unbound-history";
+      if (dryRun) {
+        migrated++;
+        results.push(`${item.slug}: would move to ${where}`);
+        continue;
+      }
+      try {
+        const added = foldHistoryInto(target, item.file);
+        unlinkSync(item.file);
+        if (!item.parked) discardEmptyFolder(dirname(item.file));
+        migrated++;
+        results.push(`${item.slug}: ${added} entr(ies) moved to ${where}`);
+      } catch (e) {
+        skipped++;
+        results.push(`${item.slug}: skipped (${(e as Error).message})`);
+      }
+    }
+
+    return { migrated, skipped, results };
+  },
+};
+
 const MIGRATIONS: Migration[] = [
   v1Projects,
   v2ThreadsToIsc,
   v3EntitiesToKnowledge,
   v4PathsToBindings,
   v5AttributionKeys,
+  v6HistorySlugs,
 ];
 
 // ── Public API ────────────────────────────────────────────────────

package/src/hooks/lib/paths.ts

@@ -97,6 +97,7 @@ export const paths = {
   ledger: () => ensureDir(home("memory", "ledger")),
   progress: () => ensureDir(home("memory", "state", "progress")),
   projectHistory: () => ensureDir(home("memory", "projects")),
+  unboundHistory: () => ensureDir(home("memory", "state", "unbound-history")),
   sessionLearning: () => ensureDir(home("memory", "learning", "session")),
   synthesis: () => ensureDir(home("memory", "learning", "synthesis")),
   work: () => ensureDir(home("memory", "work")),

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);