portable-agent-layer 0.76.0 → 0.77.0

package/README.md

@@ -77,7 +77,7 @@ pal cli status        # check your setup
 | `pal cli init` | Scaffold PAL home directory and install hooks |
 | `pal cli install` | Register hooks/skills for targets |
 | `pal cli uninstall` | Remove hooks/skills for targets |
-| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks |
+| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this daily on its own; the switch lives in the control room under Settings → Updates. On a repo install a daily run waits while the clone has uncommitted changes |
 | `pal cli export` | Export user state (telos, memory) to a zip |
 | `pal cli import` | Import user state from a zip |
 | `pal cli status` | Show current PAL configuration |

package/assets/skills/consulting-report/tools/generate-pdf.ts

@@ -28,9 +28,9 @@ interface ReportMeta {
   reportTitle: string;
   classification: string;
   consultancyName: string;
-  /** Public path to consultancy logo (e.g. "/logos/konvert7.svg"). Used in the PDF footer. */
+  /** Public path to consultancy logo (e.g. "/logos/consultancy.svg"). Used in the PDF footer. */
   consultancyLogoSrc?: string;
-  /** Public path to client logo (e.g. "/logos/transcend.svg"). Used in the PDF header. */
+  /** Public path to client logo (e.g. "/logos/client.svg"). Used in the PDF header. */
   clientLogoSrc?: string;
 }
 

package/package.json

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

package/src/cli/index.ts

@@ -1245,10 +1245,12 @@ async function install(targets: Targets) {
     await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");
   const { promptAttribution } = await import("./setup-attribution");
+  const { promptAutoUpdate } = await import("./setup-auto-update");
   scaffoldTelos();
   scaffoldPalSettings();
   await promptIdentity();
   await promptAttribution();
+  await promptAutoUpdate();
   pointAtOnboarding();
 
   // Registers the label loadActor derives, so it travels on the next export.

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/cli/setup-auto-update.ts

@@ -0,0 +1,45 @@
+/**
+ * Daily unattended updates — one-time opt-in prompt.
+ *
+ * Asked once during `pal install`, the same seam git attribution uses, so a new
+ * user sees it at init and an existing one on their next update. The non-TTY
+ * guard is load-bearing twice over: it keeps CI silent, and it keeps the
+ * reinstall at the end of an unattended update from waiting on an answer nobody
+ * is there to give.
+ */
+
+import * as clack from "@clack/prompts";
+import { isRepoMode } from "../hooks/handlers/update-check";
+import { raw as readSettings, write as writeSettings } from "../hooks/lib/settings";
+
+/** Only a git clone can be mid-change; a global package install has no such state. */
+function whatItDoes(): string {
+  const daily = "Once a day, at session start, PAL updates itself in the background.";
+  return isRepoMode()
+    ? `${daily}\nIt waits while this clone has uncommitted changes.`
+    : daily;
+}
+
+export async function promptAutoUpdate(): Promise<void> {
+  if (!process.stdin.isTTY) return;
+
+  const settings = { ...readSettings() };
+  if (settings.autoUpdate?.decided) return;
+
+  clack.intro("Automatic updates");
+  clack.note(whatItDoes(), "Keep PAL up to date on its own?");
+
+  const enabled = await clack.confirm({
+    message: "Turn on daily automatic updates?",
+    initialValue: false,
+  });
+  if (clack.isCancel(enabled)) {
+    clack.cancel("Skipped — will ask again next time");
+    return;
+  }
+
+  settings.autoUpdate = { enabled: enabled === true, decided: true };
+  writeSettings(settings);
+  const state = enabled ? "Daily updates on" : "Daily updates off";
+  clack.outro(`${state} ✓  ·  change later: control room → Settings → Updates`);
+}

package/src/hooks/AutoUpdate.ts

@@ -0,0 +1,16 @@
+/**
+ * Spawned, never awaited — runs the daily self-update in a process of its own.
+ *
+ * LoadContext decides whether today's update is due; the control room's button
+ * starts this directly. Either way the work happens here so nothing waits on a
+ * git pull and a reinstall.
+ */
+
+import { runAutoUpdate } from "./lib/auto-update";
+import { logError } from "./lib/log";
+
+try {
+  runAutoUpdate();
+} catch (err) {
+  logError("AutoUpdate", err);
+}

package/src/hooks/LoadContext.ts

@@ -11,6 +11,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { getActiveAgent } from "./lib/agent";
+import { shouldAutoUpdate, spawnAutoUpdate } from "./lib/auto-update";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { type AgentTarget, buildSystemReminder } from "./lib/context";
 import { logContextSnapshot, logDebug, logError } from "./lib/log";
@@ -38,6 +39,12 @@ try {
   logError("LoadContext:regenerate", err);
 }
 
+try {
+  if (shouldAutoUpdate()) spawnAutoUpdate();
+} catch (err) {
+  logError("LoadContext:auto-update", err);
+}
+
 try {
   const active = getActiveAgent();
   // The reminder is built for one of three targets; every other agent reads the

package/src/hooks/handlers/agenda.ts

@@ -343,7 +343,7 @@ async function writeMoves(sessionId?: string): Promise<boolean> {
       "You write the first three lines a person reads in the morning.",
       "You are given their goals and a ranked list of their projects and goals with the reason each was ranked.",
       "Write exactly three moves, most consequential first.",
-      "A move is a sentence naming an action, not a project name: 'Send ACE the mapping one-pager' beats 'work on ontology'.",
+      "A move is a sentence naming an action, not a project name: 'Send the supplier the revised quote' beats 'work on billing'.",
       "Prefer what is blocked on the person themselves, then what serves a goal, then what is merely urgent.",
       "Name the project each move belongs to, copying its slug exactly from the list you were given. A move that belongs to no project takes an empty string.",
       "Never invent a fact that is not in what you were given.",

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

@@ -12,7 +12,7 @@ import { resolve } from "node:path";
 import { logDebug } from "../lib/log";
 import { ensureDir, palPkg, paths } from "../lib/paths";
 
-interface UpdateCache {
+export interface UpdateCache {
   checkedAt: string;
   available: boolean;
   current: string;
@@ -26,18 +26,24 @@ function cachePath(): string {
   return resolve(ensureDir(paths.state()), "update-available.json");
 }
 
-function readCache(): UpdateCache | null {
+/** The last check's result whatever its age — the notice and the page read this, not the TTL. */
+export function cachedStatus(): UpdateCache | null {
   try {
     const fp = cachePath();
     if (!existsSync(fp)) return null;
-    const cache = JSON.parse(readFileSync(fp, "utf-8")) as UpdateCache;
-    if (Date.now() - new Date(cache.checkedAt).getTime() < CACHE_TTL_MS) return cache;
-    return null; // expired
+    return JSON.parse(readFileSync(fp, "utf-8")) as UpdateCache;
   } catch {
     return null;
   }
 }
 
+function readCache(): UpdateCache | null {
+  const cache = cachedStatus();
+  if (!cache) return null;
+  const fresh = Date.now() - new Date(cache.checkedAt).getTime() < CACHE_TTL_MS;
+  return fresh ? cache : null;
+}
+
 function writeCache(cache: UpdateCache): void {
   try {
     writeFileSync(cachePath(), JSON.stringify(cache, null, 2), "utf-8");
@@ -50,7 +56,7 @@ export function isRepoMode(): boolean {
   return existsSync(resolve(palPkg(), ".git"));
 }
 
-function getInstalledVersion(): string {
+export function getInstalledVersion(): string {
   try {
     const pkg = JSON.parse(readFileSync(resolve(palPkg(), "package.json"), "utf-8"));
     return pkg.version || "0.0.0";
@@ -193,14 +199,7 @@ export function clearUpdateCache(): void {
 
 /** Read cached update status for greeting display. Returns null if no update. */
 export function getUpdateNotice(): string | null {
-  try {
-    const fp = cachePath();
-    if (!existsSync(fp)) return null;
-    const cache = JSON.parse(readFileSync(fp, "utf-8")) as UpdateCache;
-    if (!cache.available) return null;
-
-    return `📦 Update available: ${cache.current} → ${cache.latest} (pal cli update)`;
-  } catch {
-    return null;
-  }
+  const cache = cachedStatus();
+  if (!cache?.available) return null;
+  return `📦 Update available: ${cache.current} → ${cache.latest} (pal cli update)`;
 }

package/src/hooks/lib/auto-update.ts

@@ -0,0 +1,184 @@
+/**
+ * The daily self-update: when it may run unattended, and what came of it.
+ *
+ * `pal cli update` still owns the pull and the reinstall — this module only
+ * decides whether to start it and records the outcome, so the command shape
+ * lives in exactly one place.
+ *
+ * The ledger in state/auto-update.json is deliberately not update-available.json:
+ * that one is an hourly detection cache, this one is the record of what was
+ * attempted. A skip is stamped separately from an attempt so that skipping today
+ * never consumes today's attempt.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { cachedStatus, getInstalledVersion, isRepoMode } from "../handlers/update-check";
+import { logDebug, logError } from "./log";
+import { assets, palPkg, paths } from "./paths";
+import { raw as rawSettings } from "./settings";
+
+export interface AutoUpdateLedger {
+  attemptedAt?: string;
+  finishedAt?: string;
+  ok?: boolean;
+  from?: string;
+  to?: string;
+  error?: string;
+  skippedAt?: string;
+  skipped?: string;
+}
+
+export interface AutoUpdateStatus {
+  enabled: boolean;
+  decided: boolean;
+  current: string;
+  latest: string | null;
+  available: boolean;
+  checkedAt: string | null;
+  mode: "repo" | "package";
+  last: AutoUpdateLedger | null;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DIRTY_TREE = "uncommitted changes in the PAL repo";
+
+function ledgerPath(): string {
+  return resolve(paths.state(), "auto-update.json");
+}
+
+function logPath(): string {
+  return resolve(paths.state(), "auto-update.log");
+}
+
+export function readLedger(): AutoUpdateLedger | null {
+  try {
+    const fp = ledgerPath();
+    if (!existsSync(fp)) return null;
+    return JSON.parse(readFileSync(fp, "utf-8")) as AutoUpdateLedger;
+  } catch {
+    return null;
+  }
+}
+
+function writeLedger(entry: AutoUpdateLedger): AutoUpdateLedger {
+  try {
+    writeFileSync(ledgerPath(), `${JSON.stringify(entry, null, 2)}\n`, "utf-8");
+  } catch (err) {
+    logError("auto-update:ledger", err);
+  }
+  return entry;
+}
+
+function isAutoUpdateEnabled(): boolean {
+  return rawSettings().autoUpdate?.enabled === true;
+}
+
+export function autoUpdateStatus(): AutoUpdateStatus {
+  const settings = rawSettings().autoUpdate ?? {};
+  const cache = cachedStatus();
+  return {
+    enabled: settings.enabled === true,
+    decided: settings.decided === true,
+    current: cache?.current ?? getInstalledVersion(),
+    latest: cache?.latest ?? null,
+    available: cache?.available === true,
+    checkedAt: cache?.checkedAt ?? null,
+    mode: cache?.mode ?? (isRepoMode() ? "repo" : "package"),
+    last: readLedger(),
+  };
+}
+
+/**
+ * A pull cannot fast-forward over uncommitted work, so an unattended update on a
+ * dirty clone would fail every night. It waits instead, and says so.
+ */
+function hasUncommittedChanges(): boolean {
+  if (!isRepoMode()) return false;
+  const status = spawnSync("git", ["status", "--porcelain"], {
+    cwd: palPkg(),
+    encoding: "utf-8",
+    windowsHide: true,
+  });
+  if (status.status !== 0) return false;
+  return (status.stdout ?? "").trim().length > 0;
+}
+
+function recordSkip(reason: string): void {
+  writeLedger({ ...readLedger(), skippedAt: new Date().toISOString(), skipped: reason });
+  logDebug("auto-update", `skipped: ${reason}`);
+}
+
+function attemptedWithin(ledger: AutoUpdateLedger | null, now: number): boolean {
+  if (!ledger?.attemptedAt) return false;
+  return now - new Date(ledger.attemptedAt).getTime() < DAY_MS;
+}
+
+/** The unattended gate: opted in, not already tried today, and safe to pull. */
+export function shouldAutoUpdate(now: number = Date.now()): boolean {
+  if (!isAutoUpdateEnabled()) return false;
+  if (attemptedWithin(readLedger(), now)) return false;
+  if (hasUncommittedChanges()) {
+    recordSkip(DIRTY_TREE);
+    return false;
+  }
+  return true;
+}
+
+function updateCommand(): string[] {
+  return [resolve(palPkg(), "src", "cli", "index.ts"), "cli", "update"];
+}
+
+/**
+ * Runs in the detached child, never in the hook that spawned it. The attempt is
+ * stamped before the command starts so a run that dies mid-flight still counts
+ * against today — a broken update retries tomorrow, not every session.
+ */
+export function runAutoUpdate(): AutoUpdateLedger {
+  if (hasUncommittedChanges()) {
+    recordSkip(DIRTY_TREE);
+    return readLedger() ?? {};
+  }
+
+  const from = getInstalledVersion();
+  writeLedger({ attemptedAt: new Date().toISOString(), from });
+
+  const run = spawnSync("bun", updateCommand(), {
+    cwd: palPkg(),
+    encoding: "utf-8",
+    windowsHide: true,
+  });
+  const output = `${run.stdout ?? ""}${run.stderr ?? ""}`;
+  try {
+    writeFileSync(logPath(), output, "utf-8");
+  } catch (err) {
+    logError("auto-update:log", err);
+  }
+
+  const ok = run.status === 0;
+  logDebug("auto-update", `update exited ${run.status}`);
+  return writeLedger({
+    ...readLedger(),
+    finishedAt: new Date().toISOString(),
+    ok,
+    from,
+    to: getInstalledVersion(),
+    error: ok ? undefined : (run.error?.message ?? `exit ${run.status}`),
+  });
+}
+
+/** Hands the update to its own process so session start never waits on it. */
+export function spawnAutoUpdate(): void {
+  try {
+    const child = spawn("bun", [resolve(assets.hooks(), "AutoUpdate.ts")], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+    logDebug("auto-update", "detached update spawned");
+  } catch (err) {
+    logError("auto-update:spawn", err);
+  }
+}

package/src/hooks/lib/goal-links.ts

@@ -1,8 +1,8 @@
 /**
  * Which projects serve which stated goal, and how far along that makes it.
  *
- * The linkage needs judgement — "Catalyst is the starter that pays for the rest"
- * serves "land two retained clients" only if you know what both mean — so a model
+ * The linkage needs judgement — "the starter kit is what pays for the rest"
+ * serves "reach steady revenue" only if you know what both mean — so a model
  * draws it. The progress does not: it is criteria closed over criteria written,
  * counted here, because a model returning "64%" says something unfalsifiable
  * about a goal it cannot measure.

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/security.ts

@@ -14,7 +14,7 @@ const WIN_RECURSE_FLAG = String.raw`(?:-(?:r(?:e(?:c(?:u(?:r(?:se?)?)?)?)?)?f?|f
 
 /**
  * A whole root, not a directory inside one. The trailing lookahead is the part
- * that matters: without it `C:\` prefix-matches `C:\Users\rico\dist` and every
+ * that matters: without it `C:\` prefix-matches `C:\Users\user\dist` and every
  * ordinary recursive delete on Windows gets blocked.
  */
 const WIN_ROOT_TARGET = String.raw`["']?(?:[a-z]:[\\/]?\*?|\\\\|~|\$home|\$env:userprofile|\$env:systemdrive)["']?(?=["'\s;,)]|$)`;

package/src/hooks/lib/settings.ts

@@ -25,6 +25,8 @@ export interface PalSettingsData {
   dynamicContext?: Record<string, boolean>;
   /** Git co-author attribution opt-in. `decided` gates the one-time prompt. */
   attribution?: { enabled?: boolean; decided?: boolean };
+  /** Daily unattended self-update opt-in. `decided` gates the one-time prompt. */
+  autoUpdate?: { enabled?: boolean; decided?: boolean };
   /**
    * Action-ledger user extension. `redactPaths` adds to the built-in set of
    * paths whose contents are never stored; it cannot shrink it.

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