portable-agent-layer 0.78.1 → 0.78.3

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. Install asks once whether to do this daily on its own, applied when a session closes so opening PAL is never slowed; 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 update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this on its own: when a session closes PAL checks for a release (at most hourly) and installs it, so opening PAL is never slowed. A failed update waits a day before retrying. The switch lives in the control room under Settings → Updates. On a repo install an update 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 |
@@ -156,7 +156,7 @@ PAL routes inference through the host agent's subscription CLI by default. API k
 Enable verbose hook logging with:
 
 ```
-pal cli debug on    # enable  → logs to memory/state/debug.log
+pal cli debug on    # enable  → logs to debug/debug.log
 pal cli debug off   # disable
 pal cli debug       # show current status and log path
 ```
@@ -165,6 +165,7 @@ pal cli debug       # show current status and log path
 |----------|-------------|
 | `PAL_INFERENCE_DISABLED` | Set to `1` to disable all inference (used by the test suite to prevent real CLI spawns) |
 | `PAL_NOTIFICATIONS_DISABLED` | Set to `1` to suppress desktop notifications (used by the test suite) |
+| `PAL_TEST_SANDBOX` | Set by the test suite. Without a `PAL_HOME`, state goes to a temp directory instead of `~/.pal`, and installers refuse to touch real agent directories |
 
 ---
 

package/assets/skills/pal-reflect/SKILL.md

@@ -19,10 +19,10 @@ When `/pal-reflect` is invoked (by you in response to a nudge, or by the user di
 ## 1. Run the reflect tool
 
 ```bash
-bun run tool:reflect
+pal cli relationship-reflect
 ```
 
-If the user passed `--dry-run`, append it: `bun run tool:reflect -- --dry-run`
+If the user passed `--dry-run`, append it: `pal cli relationship-reflect --dry-run`
 
 ## 2. Parse and present the output
 

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -383,7 +383,7 @@ Relationship notes (O/B types)
 - Content is global/user-level — safe to pre-compile (not project-scoped)
 
 **Tier 3 — Dynamic** (injected fresh each session by LoadContext hook):
-- Handoff notes, session intelligence, open threads, relationship notes, project history
+- Handoff notes, session intelligence, relationship notes, project history
 - Changes per-session or is project-scoped — can't be pre-compiled
 - Injected as `<system-reminder>` block via stdout
 - Each section independently toggleable in `pal-settings.json → dynamicContext`
@@ -402,12 +402,12 @@ LoadContext.ts
   └─► Build system-reminder (dynamic sections only):
       1. loadAtStartup files (user-configured)
       2. Handoff note (in-progress work from last session)
-      3. Session intelligence (rating trend, algorithm performance)
-      4. Open threads (current project only)
+      3. Due nudges (algorithm review, relationship reflect, learning analysis)
+      4. Session intelligence (rating trend, algorithm performance)
       5. Recent interaction notes (last 2 days)
       6. Active projects
       7. Project session history (this project)
-      8. Signal trends (today/week/trend)
+      8. Other recent learnings (other projects, titles only)
 ```
 
 ### On-Demand Context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.78.1",
+  "version": "0.78.3",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -64,7 +64,7 @@
     "tool:synthesize": "bun run src/tools/agent/synthesize.ts",
     "tool:thread": "bun run src/tools/agent/thread.ts",
     "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.ts",
-    "tool:reflect": "bun run src/tools/relationship-reflect.ts",
+    "tool:reflect": "bun run src/tools/agent/relationship-reflect.ts",
     "eval:sentiment": "bun eval/run.ts sentiment",
     "eval:failure-principle": "bun eval/run.ts failure-principle",
     "eval:goal-links": "bun eval/run.ts goal-links",

package/src/cli/builtin-tools.ts

@@ -13,6 +13,7 @@ const BUILTIN_TOOLS = {
   "handoff-note": () => import("../tools/agent/handoff-note"),
   project: () => import("../tools/agent/project"),
   "relationship-note": () => import("../tools/agent/relationship-note"),
+  "relationship-reflect": () => import("../tools/agent/relationship-reflect"),
   synthesize: () => import("../tools/agent/synthesize"),
   thread: () => import("../tools/agent/thread"),
   "wisdom-frame": () => import("../tools/agent/wisdom-frame"),

package/src/cli/index.ts

@@ -47,7 +47,7 @@ import {
   summarize,
 } from "../hooks/lib/import-merge";
 import { inference, previewInferenceRoute } from "../hooks/lib/inference";
-import { DEBUG_LOG_MAX_ROTATED, logDebug } from "../hooks/lib/log";
+import { logDebug, recentHookErrors } from "../hooks/lib/log";
 import { ensureRegistered, writeRegistryEntry } from "../hooks/lib/machine";
 import { palHome, palPkg, paths, platform, toPath } from "../hooks/lib/paths";
 import { auditBindings, describeBindingIssue } from "../hooks/lib/projects";
@@ -462,11 +462,6 @@ function resolveTargets(args: string[], health?: DoctorResult): Targets {
 
 // ── Hook health ──
 
-interface HookHealth {
-  totalErrors: number;
-  lastError: string | null;
-}
-
 function checkClaudeHooksRegistered(): boolean {
   const settingsPath = resolve(platform.claudeDir(), "settings.json");
   if (!existsSync(settingsPath)) return false;
@@ -645,7 +640,7 @@ async function probeInference(): Promise<void> {
         );
       } else {
         console.log(
-          `  ${red}✗${reset} ${tag} ${String(elapsedMs).padStart(6)}ms  ${dim}failed — see ~/.pal/memory/state/debug.log${reset}`
+          `  ${red}✗${reset} ${tag} ${String(elapsedMs).padStart(6)}ms  ${dim}failed — see ~/.pal/debug/debug.log${reset}`
         );
       }
     }
@@ -733,46 +728,6 @@ function rtkInstallHint(): string {
   return "`curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh`";
 }
 
-function checkHookHealth(home: string): HookHealth {
-  const stateDir = resolve(home, "memory", "state");
-  // Read current + all rotated logs (`.1`..`.5`) + legacy `.prev` so a recent
-  // rotation doesn't make the 24h window appear empty.
-  const candidates = [
-    resolve(stateDir, "debug.log"),
-    resolve(stateDir, "debug.log.prev"),
-    ...Array.from({ length: DEBUG_LOG_MAX_ROTATED }, (_, i) =>
-      resolve(stateDir, `debug.log.${i + 1}`)
-    ),
-  ];
-
-  try {
-    let content = "";
-    for (const path of candidates) {
-      if (existsSync(path)) content += `${readFileSync(path, "utf-8")}\n`;
-    }
-    if (!content) return { totalErrors: 0, lastError: null };
-
-    const lines = content.split("\n").filter((l) => l.includes("] ERROR "));
-
-    // Filter to last 24h
-    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
-    const recentErrors = lines.filter((line) => {
-      const match = new RegExp(/^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\]/).exec(line);
-      if (!match) return false;
-      return new Date(match[1]) > cutoff;
-    });
-
-    const lastError =
-      recentErrors.length > 0
-        ? (recentErrors.at(-1) ?? "").replace(/^\[.*?\] ERROR /, "").slice(0, 120)
-        : null;
-
-    return { totalErrors: recentErrors.length, lastError };
-  } catch {
-    return { totalErrors: 0, lastError: null };
-  }
-}
-
 // ── Doctor ──
 
 interface DoctorResult {
@@ -1131,7 +1086,7 @@ function doctor(silent = false): DoctorResult {
       : warn("PAL_PERPLEXITY_API_KEY — not set (optional, for Perplexity researcher)");
 
     // Hook health from debug.log
-    const hookHealth = checkHookHealth(home);
+    const hookHealth = recentHookErrors();
     if (hookHealth.totalErrors === 0) {
       ok("Hooks: no recent errors");
     } else {

package/src/cli/setup-auto-update.ts

@@ -1,5 +1,5 @@
 /**
- * Daily unattended updates — one-time opt-in prompt.
+ * 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
@@ -14,11 +14,11 @@ import { raw as readSettings, write as writeSettings } from "../hooks/lib/settin
 
 /** Only a git clone can be mid-change; a global package install has no such state. */
 function whatItDoes(): string {
-  const daily =
-    "Once a day, when you close a session, PAL updates itself in the background.\nOpening PAL is never slowed down, and the statusline says when to restart.";
+  const onClose =
+    "When you close a session, PAL checks for a new release (at most hourly) and installs it in the background.\nOpening PAL is never slowed down, and the statusline says when to restart.";
   return isRepoMode()
-    ? `${daily}\nIt waits while this clone has uncommitted changes.`
-    : daily;
+    ? `${onClose}\nIt waits while this clone has uncommitted changes.`
+    : onClose;
 }
 
 export async function promptAutoUpdate(): Promise<void> {
@@ -31,7 +31,7 @@ export async function promptAutoUpdate(): Promise<void> {
   clack.note(whatItDoes(), "Keep PAL up to date on its own?");
 
   const enabled = await clack.confirm({
-    message: "Turn on daily automatic updates?",
+    message: "Turn on automatic updates?",
     initialValue: false,
   });
   if (clack.isCancel(enabled)) {
@@ -41,6 +41,6 @@ export async function promptAutoUpdate(): Promise<void> {
 
   settings.autoUpdate = { enabled: enabled === true, decided: true };
   writeSettings(settings);
-  const state = enabled ? "Daily updates on" : "Daily updates off";
+  const state = enabled ? "Automatic updates on" : "Automatic updates off";
   clack.outro(`${state} ✓  ·  change later: control room → Settings → Updates`);
 }

package/src/hooks/AutoUpdate.ts

@@ -1,5 +1,5 @@
 /**
- * Spawned, never awaited — runs the daily self-update in a process of its own.
+ * Spawned, never awaited — runs the unattended 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

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

@@ -35,6 +35,34 @@ function isProtectedHandoff(entry: unknown): boolean {
   return Date.now() - new Date(e.timestamp).getTime() <= HANDOFF_STALE_MS;
 }
 
+interface AutoHandoff {
+  title: string;
+  status: string;
+  handoff: string;
+}
+
+function readHandoffs(handoffPath: string): Record<string, unknown> {
+  try {
+    return existsSync(handoffPath) ? JSON.parse(readFileSync(handoffPath, "utf-8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Record this cwd's handoff unless a fresh deliberate note already owns it (ISC-39). */
+export function writeAutoHandoff(cwd: string, entry: AutoHandoff): void {
+  const handoffPath = resolve(ensureDir(paths.state()), "last-handoff.json");
+  const existing = readHandoffs(handoffPath);
+  if (isProtectedHandoff(existing[cwd])) return;
+  existing[cwd] = {
+    timestamp: new Date().toISOString(),
+    ...entry,
+    artifacts: [],
+    source: "auto",
+  };
+  writeFileSync(handoffPath, JSON.stringify(existing, null, 2), "utf-8");
+}
+
 export function persistLastExchange(
   messages: ParsedMessage[],
   sessionId: string,
@@ -59,30 +87,17 @@ export function persistLastExchange(
     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" — unless a
-    //    fresh deliberate note already owns this cwd (ISC-39).
-    const handoffPath = resolve(paths.state(), "last-handoff.json");
-    const existing: Record<string, unknown> = existsSync(handoffPath)
-      ? JSON.parse(readFileSync(handoffPath, "utf-8"))
-      : {};
-    if (!isProtectedHandoff(existing[cwd])) {
-      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: [],
-        source: "auto",
-      };
-      writeFileSync(handoffPath, JSON.stringify(existing, null, 2), "utf-8");
-    }
+    const handoff = [
+      lastUser ? `Last user message:\n${lastUser.slice(0, 500)}` : "",
+      lastAssistant ? `\nLast assistant response:\n${lastAssistant.slice(0, 500)}` : "",
+    ]
+      .filter(Boolean)
+      .join("");
+    writeAutoHandoff(cwd, {
+      title: (lastUser.slice(0, 80).replace(/\n/g, " ") || "Session").trim(),
+      status: detectStatus(lastAssistant),
+      handoff,
+    });
 
     logDebug(
       "persist-last-exchange",

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

@@ -1,8 +1,8 @@
 /**
  * Stop handler: unified session intelligence capture.
  *
- * Produces: title, summary, insights via Haiku.
- * Writes: session learning file, project history.
+ * Produces: title, summary, insights, handoff via Haiku.
+ * Writes: session learning file, project history, auto handoff (in-progress only).
  *
  * Relationship notes → written in ALGORITHM LEARN phase via relationship-note.ts
  * Handoff notes     → written in ALGORITHM LEARN phase via handoff-note.ts
@@ -32,6 +32,7 @@ import {
   parseMessages,
 } from "../lib/transcript";
 import { appendProjectHistory, detectStatus } from "../lib/work-tracking";
+import { writeAutoHandoff } from "./persist-last-exchange";
 
 // ── JSON schema for merged Haiku call ──
 
@@ -140,6 +141,9 @@ export async function captureSessionIntelligence(
   const title = output?.title || extractContent(lastUser).slice(0, 80) || "session";
   const summary = output?.summary || lastAssistantText.slice(0, 600);
   const insights = output?.insights || "";
+  if (status === "in-progress" && output?.handoff) {
+    writeAutoHandoff(process.cwd(), { title, status, handoff: output.handoff });
+  }
   // ── Write session learning file ──
 
   const category = categorizeLearning(title, summary);

package/src/hooks/lib/algorithm-review.ts

@@ -35,11 +35,13 @@ export function writeReviewMark(ts: string): void {
   writeFileSync(markFile(), `${JSON.stringify({ lastReviewedTs: ts }, null, 2)}\n`);
 }
 
-/** True only in a maintainer repo checkout — the repo-only update skill is present. */
-export function isMaintainerEnv(): boolean {
-  return existsSync(
-    resolve(palPkg(), ".agents", "skills", "algorithm-update", "SKILL.md")
-  );
+function hasAlgorithmUpdateSkill(root: string): boolean {
+  return existsSync(resolve(root, ".agents", "skills", "algorithm-update", "SKILL.md"));
+}
+
+/** True when PAL runs from its checkout, or a session is working inside one. */
+export function isMaintainerEnv(cwd: string = process.cwd()): boolean {
+  return hasAlgorithmUpdateSkill(palPkg()) || hasAlgorithmUpdateSkill(cwd);
 }
 
 /** Count reflections newer than the last review mark (all of them, if never reviewed). */
@@ -60,8 +62,11 @@ export interface ReviewNudge {
  * Nudge data when BOTH thresholds are met (≥25 new AND ≥7 days) in a maintainer
  * env, else null. `now` is injected for testability.
  */
-export function algorithmReviewNudge(now: Date): ReviewNudge | null {
-  if (!isMaintainerEnv()) return null;
+export function algorithmReviewNudge(
+  now: Date,
+  cwd: string = process.cwd()
+): ReviewNudge | null {
+  if (!isMaintainerEnv(cwd)) return null;
   const mark = readReviewMark();
   const count = countUnreviewed(mark);
   if (count < NUDGE_MIN_COUNT) return null;

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

@@ -1,5 +1,5 @@
 /**
- * The daily self-update: when it may run unattended, and what came of it.
+ * The unattended self-update: when it may run, 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
@@ -41,7 +41,8 @@ export interface AutoUpdateStatus {
   last: AutoUpdateLedger | null;
 }
 
-const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
 const RESCUE_AFTER_MS = 3 * DAY_MS;
 const LOCK_STALE_MS = 30 * 60 * 1000;
 const DIRTY_TREE = "uncommitted changes in the PAL repo";
@@ -122,15 +123,24 @@ function recordSkip(reason: string): void {
   logDebug("auto-update", `skipped: ${reason}`);
 }
 
-function attemptedWithin(ledger: AutoUpdateLedger | null, now: number): boolean {
+/**
+ * A clean run — including one that found nothing to install — only waits out the
+ * hour, so a release published after the morning's check still lands today. A
+ * failed or interrupted run waits a day, so a broken update cannot loop.
+ */
+function waitAfter(ledger: AutoUpdateLedger): number {
+  return ledger.ok === true ? HOUR_MS : DAY_MS;
+}
+
+function heldByLastRun(ledger: AutoUpdateLedger | null, now: number): boolean {
   if (!ledger?.attemptedAt) return false;
-  return now - new Date(ledger.attemptedAt).getTime() < DAY_MS;
+  return now - new Date(ledger.attemptedAt).getTime() < waitAfter(ledger);
 }
 
-/** The unattended gate: opted in, not already tried today, and safe to pull. */
+/** The unattended gate: opted in, not held by the last run, and safe to pull. */
 export function shouldAutoUpdate(now: number = Date.now()): boolean {
   if (!isAutoUpdateEnabled()) return false;
-  if (attemptedWithin(readLedger(), now)) return false;
+  if (heldByLastRun(readLedger(), now)) return false;
   if (hasUncommittedChanges()) {
     recordSkip(DIRTY_TREE);
     return false;

package/src/hooks/lib/context.ts

@@ -8,6 +8,7 @@ import { resolve } from "node:path";
 import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { loadAnalyzeNudge } from "./analyze-nudge";
+import { resolveAnchor } from "./anchor";
 import { readLearnings } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
 import { paths, toPath } from "./paths";
@@ -105,6 +106,11 @@ function loadProjectHistoryContext(): string {
   }
 }
 
+function stampedPath(stamp: string): string {
+  const resolved = resolveAnchor(stamp);
+  return resolved.state === "unresolvable" ? stamp : resolved.path;
+}
+
 /**
  * Filter raw relationship note lines:
  * - O entries: stripped (loaded natively via digest)
@@ -125,7 +131,7 @@ function filterRelationshipNotes(notes: string, cwd: string): string {
     }
     const cwdMatch = new RegExp(/<!--.*cwd:(\S+)/).exec(line);
     if (cwdMatch) {
-      blockCwd = cwdMatch[1];
+      blockCwd = stampedPath(cwdMatch[1]);
       continue;
     }
     if (/^\s*<!--/.test(line)) continue;

package/src/hooks/lib/inference.ts

@@ -214,40 +214,32 @@ export async function inference(opts: InferenceOptions): Promise<InferenceResult
 // Per-agent CLI metadata — binary presence + argv builders
 // ─────────────────────────────────────────────────────────────────────────────
 
-let claudeBinaryCache: string | null | undefined;
-let codexBinaryCache: string | null | undefined;
-let opencodeBinaryCache: string | null | undefined;
-let copilotBinaryCache: string | null | undefined;
-let cursorBinaryCache: string | null | undefined;
+const binaryCache = new Map<string, string | null>();
+
+function cachedBinary(name: string): string | null {
+  const key = `${name}\0${process.env.PATH ?? ""}`;
+  if (!binaryCache.has(key)) binaryCache.set(key, findBinaryOnPath(name));
+  return binaryCache.get(key) ?? null;
+}
 
 function getClaudeBinary(): string | null {
-  if (claudeBinaryCache !== undefined) return claudeBinaryCache;
-  claudeBinaryCache = findBinaryOnPath("claude");
-  return claudeBinaryCache;
+  return cachedBinary("claude");
 }
 
 function getCodexBinary(): string | null {
-  if (codexBinaryCache !== undefined) return codexBinaryCache;
-  codexBinaryCache = findBinaryOnPath("codex");
-  return codexBinaryCache;
+  return cachedBinary("codex");
 }
 
 function getOpencodeBinary(): string | null {
-  if (opencodeBinaryCache !== undefined) return opencodeBinaryCache;
-  opencodeBinaryCache = findBinaryOnPath("opencode");
-  return opencodeBinaryCache;
+  return cachedBinary("opencode");
 }
 
 function getCopilotBinary(): string | null {
-  if (copilotBinaryCache !== undefined) return copilotBinaryCache;
-  copilotBinaryCache = findBinaryOnPath("copilot");
-  return copilotBinaryCache;
+  return cachedBinary("copilot");
 }
 
 function getCursorBinary(): string | null {
-  if (cursorBinaryCache !== undefined) return cursorBinaryCache;
-  cursorBinaryCache = findBinaryOnPath("cursor-agent");
-  return cursorBinaryCache;
+  return cachedBinary("cursor-agent");
 }
 
 function hasClaudeBinary(): boolean {
@@ -266,31 +258,6 @@ function hasCursorBinary(): boolean {
   return getCursorBinary() !== null;
 }
 
-/** Test-only: reset the cached claude-binary resolution. */
-export function _resetClaudeBinaryCache(): void {
-  claudeBinaryCache = undefined;
-}
-
-/** Test-only: reset the cached codex-binary resolution. */
-export function _resetCodexBinaryCache(): void {
-  codexBinaryCache = undefined;
-}
-
-/** Test-only: reset the cached opencode-binary resolution. */
-export function _resetOpencodeBinaryCache(): void {
-  opencodeBinaryCache = undefined;
-}
-
-/** Test-only: reset the cached copilot-binary resolution. */
-export function _resetCopilotBinaryCache(): void {
-  copilotBinaryCache = undefined;
-}
-
-/** Test-only: reset the cached cursor-binary resolution. */
-export function _resetCursorBinaryCache(): void {
-  cursorBinaryCache = undefined;
-}
-
 /**
  * Build the argv for `claude --print …`. Pure.
  *

package/src/hooks/lib/log.ts

@@ -1,6 +1,6 @@
 /**
  * Simple file-based debug logger for PAL hooks.
- * Writes to memory/state/debug.log — rotated on each session start.
+ * Writes to debug/debug.log, rotated by size.
  *
  * Only writes when debug is enabled (`pal cli debug on`) or when called via logError (always logged).
  */
@@ -8,6 +8,7 @@
 import {
   appendFileSync,
   existsSync,
+  readFileSync,
   renameSync,
   statSync,
   unlinkSync,
@@ -78,8 +79,48 @@ function rotateIfNeeded(path: string): void {
   }
 }
 
-/** Test-only: max rotated count for callers that need to enumerate. */
-export const DEBUG_LOG_MAX_ROTATED = MAX_ROTATED;
+export interface HookHealth {
+  totalErrors: number;
+  lastError: string | null;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function logFilesOldestFirst(): string[] {
+  const path = logFile();
+  const rotated = Array.from(
+    { length: MAX_ROTATED },
+    (_, i) => `${path}.${MAX_ROTATED - i}`
+  );
+  return [...rotated, `${path}.prev`, path];
+}
+
+function readAllLogs(): string {
+  return logFilesOldestFirst()
+    .filter((path) => existsSync(path))
+    .map((path) => readFileSync(path, "utf-8"))
+    .join("\n");
+}
+
+function loggedAt(line: string): number {
+  const match = /^\[(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2})\]/.exec(line);
+  return match ? Date.parse(`${match[1]}T${match[2]}Z`) : 0;
+}
+
+export function recentHookErrors(now: number = Date.now()): HookHealth {
+  try {
+    const recent = readAllLogs()
+      .split("\n")
+      .filter((line) => line.includes("] ERROR ") && loggedAt(line) > now - DAY_MS);
+    const last = recent.at(-1);
+    return {
+      totalErrors: recent.length,
+      lastError: last ? last.replace(/^\[.*?\] ERROR /, "").slice(0, 120) : null,
+    };
+  } catch {
+    return { totalErrors: 0, lastError: null };
+  }
+}
 
 function isDebugEnabled(): boolean {
   return existsSync(resolve(palHome(), "memory", "state", "debug-enabled"));

package/src/hooks/lib/paths.ts

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { resolve } from "node:path";
 
 /**
@@ -56,8 +56,13 @@ export function palPkg(): string {
  * Always resolves to ~/.pal/ regardless of where the package lives.
  * Power users who want memory/telos versioned in a repo can override via PAL_HOME.
  */
+function defaultPalHome(): string {
+  if (process.env.PAL_TEST_SANDBOX) return resolve(tmpdir(), "pal-test-home");
+  return resolve(homedir(), ".pal");
+}
+
 export function palHome(): string {
-  return envPath("PAL_HOME", resolve(homedir(), ".pal"));
+  return envPath("PAL_HOME", defaultPalHome());
 }
 
 /** Ensure a directory exists, creating it recursively if needed */

package/src/hooks/lib/relationship.ts

@@ -76,8 +76,8 @@ export function appendNotes(notes: RelationshipNote[], sessionId?: string): Appe
 
   const timestamp = new Date().toTimeString().slice(0, 5);
   lines.push(`## ${timestamp}`);
-  if (sessionId)
-    lines.push(`<!-- session:${sessionId} cwd:${encodeAnchor(process.cwd())} -->`);
+  const session = sessionId ? `session:${sessionId} ` : "";
+  lines.push(`<!-- ${session}cwd:${encodeAnchor(process.cwd())} -->`);
 
   for (const note of fresh) {
     if (note.type === "O" && note.confidence !== undefined) {