portable-agent-layer 0.51.1 → 0.52.0

package/README.md

@@ -142,9 +142,16 @@ PAL routes inference through the host agent's subscription CLI by default. API k
 
 ### Debug / test
 
+Enable verbose hook logging with:
+
+```
+pal cli debug on    # enable  → logs to memory/state/debug.log
+pal cli debug off   # disable
+pal cli debug       # show current status and log path
+```
+
 | Variable | Description |
 |----------|-------------|
-| `PAL_DEBUG` | Set to `1` to emit verbose hook logs to `memory/state/debug.log` |
 | `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) |
 

package/assets/statusline.ps1

@@ -29,7 +29,7 @@ $COST_STR = '$' + ([math]::Round($COST, 2)).ToString("0.00")
 
 # PAL: Hook health - count ERROR lines in debug.log from last 24h
 $HOOK_ERRORS = 0
-$debugLog = Join-Path $env:USERPROFILE ".pal\memory\state\debug.log"
+$debugLog = Join-Path $env:USERPROFILE ".pal\debug\debug.log"
 if (Test-Path $debugLog) {
   $cutoff = (Get-Date).AddHours(-24)
   try {
@@ -173,7 +173,7 @@ $QUOTES = @(
   "A person who never made a mistake never tried anything new.|Albert Einstein"
   "The journey of a thousand miles begins with one step.|Lao Tzu"
   "The obstacle is the way.|Marcus Aurelius"
-  "Whether you think you can or you think you can't — you are right.|Henry Ford"
+  "Whether you think you can or you think you can't - you are right.|Henry Ford"
   "Everything should be made as simple as possible, but not simpler.|Albert Einstein"
   "You miss 100% of the shots you don't take.|Wayne Gretzky"
 )

package/assets/statusline.sh

@@ -56,7 +56,7 @@ fi
 
 # PAL: Hook health — count ERROR lines in debug.log from last 24h
 HOOK_ERRORS=0
-DEBUG_LOG="$HOME/.pal/memory/state/debug.log"
+DEBUG_LOG="$HOME/.pal/debug/debug.log"
 if [ -f "$DEBUG_LOG" ]; then
   # Cross-platform 24h cutoff: macOS uses date -v, GNU Linux uses date -d
   CUTOFF=$(date -v-24H "+%Y-%m-%d %H:%M:%S" 2>/dev/null || date -d '24 hours ago' "+%Y-%m-%d %H:%M:%S" 2>/dev/null)
@@ -209,7 +209,7 @@ QUOTES=(
   "A person who never made a mistake never tried anything new.|Albert Einstein"
   "The journey of a thousand miles begins with one step.|Lao Tzu"
   "The obstacle is the way.|Marcus Aurelius"
-  "Whether you think you can or you think you can't — you are right.|Henry Ford"
+  "Whether you think you can or you think you can't - you are right.|Henry Ford"
   "Everything should be made as simple as possible, but not simpler.|Albert Einstein"
   "You miss 100% of the shots you don't take.|Wayne Gretzky"
 )

package/assets/templates/pal-settings.json

@@ -21,10 +21,7 @@
     "opinions": true,
     "relationship": true,
     "learningDigest": true,
-    "synthesis": true,
-    "signalTrends": true,
     "failurePatterns": true,
-    "activeWork": true,
     "projectHistory": true,
     "projects": true,
     "sessionIntelligence": true,

package/package.json

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

package/src/cli/index.ts

@@ -18,14 +18,23 @@
  *   usage                             Summarize token usage and cost
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name>               Evaluate a skill against the authoring best practices
+ *   debug [on|off]                    Enable / disable verbose hook debug logging
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { inference, previewInferenceRoute } from "../hooks/lib/inference";
-import { DEBUG_LOG_MAX_ROTATED } from "../hooks/lib/log";
+import { DEBUG_LOG_MAX_ROTATED, logDebug } from "../hooks/lib/log";
 import { palHome, palPkg, platform } from "../hooks/lib/paths";
 import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 import { log } from "../targets/lib";
@@ -200,6 +209,9 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "debug":
+      cliDebug(args);
+      break;
     case "--help":
     case "-h":
     case "help":
@@ -244,6 +256,7 @@ function showHelp() {
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name>             Evaluate a skill against the authoring best practices
+    pal cli debug [on|off]                  Enable/disable verbose hook debug logging (persisted)
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)
@@ -1151,10 +1164,19 @@ async function exportState(args: string[]) {
 
   const dryRun = args.includes("--dry-run");
   const pathArg = args.find((a) => !a.startsWith("-"));
-  const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
-
+  const resolvedArg = pathArg ? resolve(pathArg) : null;
+  const argIsDir =
+    resolvedArg !== null &&
+    existsSync(resolvedArg) &&
+    statSync(resolvedArg).isDirectory();
+  const outputPath = argIsDir
+    ? resolve(resolvedArg, `pal-export-${timestamp()}.zip`)
+    : (resolvedArg ?? resolve(palHome(), `pal-export-${timestamp()}.zip`));
+
+  logDebug("export", `start dryRun=${dryRun} outputPath=${outputPath}`);
   if (dryRun) {
     const files = collectExportFiles();
+    logDebug("export", `dry-run collected ${files.length} files`);
     if (files.length === 0) {
       console.log("Nothing to export.");
     } else {
@@ -1163,6 +1185,7 @@ async function exportState(args: string[]) {
     }
   } else {
     const count = exportZip(outputPath);
+    logDebug("export", `done count=${count} path=${outputPath}`);
     if (count === 0) {
       console.log("Nothing to export.");
     } else {
@@ -1179,49 +1202,50 @@ async function importState(args: string[]) {
   const home = palHome();
   const dryRun = args.includes("--dry-run");
   const pathArg = args.find((a) => !a.startsWith("-"));
+  logDebug("import", `start dryRun=${dryRun} pathArg=${pathArg ?? "(auto)"}`);
 
-  function findLatest(): string | null {
+  function findLatestIn(dirs: string[]): string | null {
     const candidates: string[] = [];
-
-    try {
-      candidates.push(
-        ...readdirSync(home)
-          .filter((f) => f.startsWith("pal-export-") && f.endsWith(".zip"))
-          .map((f) => resolve(home, f))
-      );
-    } catch {
-      /* empty */
-    }
-
-    try {
-      const backupDir = resolve(home, "backups");
-      candidates.push(
-        ...readdirSync(backupDir)
-          .filter(
-            (f) =>
-              (f.startsWith("pal-export-") || f.startsWith("pal-backup-")) &&
-              f.endsWith(".zip")
-          )
-          .map((f) => resolve(backupDir, f))
-      );
-    } catch {
-      /* empty */
+    for (const dir of dirs) {
+      try {
+        candidates.push(
+          ...readdirSync(dir)
+            .filter(
+              (f) =>
+                (f.startsWith("pal-export-") || f.startsWith("pal-backup-")) &&
+                f.endsWith(".zip")
+            )
+            .map((f) => resolve(dir, f))
+        );
+      } catch {
+        /* empty */
+      }
     }
-
     if (candidates.length === 0) return null;
     return candidates.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)[0];
   }
 
   let zipPath: string;
 
-  if (pathArg) {
-    zipPath = resolve(pathArg);
+  const resolvedArg = pathArg ? resolve(pathArg) : null;
+  const argIsDir =
+    resolvedArg !== null &&
+    existsSync(resolvedArg) &&
+    statSync(resolvedArg).isDirectory();
+
+  if (resolvedArg && !argIsDir) {
+    zipPath = resolvedArg;
+    logDebug("import", `using provided path=${zipPath}`);
   } else {
-    const latest = findLatest();
+    const searchDirs = argIsDir ? [resolvedArg] : [home, resolve(home, "backups")];
+    logDebug("import", `searching dirs=${searchDirs.join(",")}`);
+    const latest = findLatestIn(searchDirs);
     if (!latest) {
+      logDebug("import", "no export/backup files found");
       log.error("No export or backup files found. Provide a path: pal cli import <path>");
       process.exit(1);
     }
+    logDebug("import", `auto-selected latest=${latest}`);
     console.log(`Found: ${latest}`);
     const zip = new AdmZip(latest);
     console.log(
@@ -1253,11 +1277,13 @@ async function importState(args: string[]) {
     process.exit(0);
   }
 
+  logDebug("import", `zip=${zipPath} entries=${entries.length} dryRun=${dryRun}`);
   if (dryRun) {
     console.log(`Would import ${entries.length} files → ${home}\n`);
     for (const e of entries) console.log(`  ${e.entryName}`);
   } else {
     zip.extractAllTo(home, true);
+    logDebug("import", `done extracted=${entries.length} to=${home}`);
     console.log(`Imported ${entries.length} files → ${home}`);
     log.info("Run 'pal cli install' to re-register hooks.");
   }
@@ -1309,6 +1335,25 @@ async function update() {
   await install(resolveTargets([]));
 }
 
+function cliDebug(args: string[]) {
+  const stateDir = resolve(palHome(), "memory", "state");
+  const flagFile = resolve(stateDir, "debug-enabled");
+  const logFile = resolve(stateDir, "debug.log");
+  const sub = args[0];
+  if (sub === "on") {
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(flagFile, "");
+    log.success(`Debug logging enabled → ${logFile}`);
+  } else if (sub === "off") {
+    rmSync(flagFile, { force: true });
+    log.success("Debug logging disabled");
+  } else {
+    const on = existsSync(flagFile);
+    console.log(`  Debug: ${on ? "ON" : "OFF"}`);
+    console.log(`  Log:   ${logFile}`);
+  }
+}
+
 async function status() {
   const home = palHome();
   const pkg = palPkg();

package/src/hooks/LoadContext.ts

@@ -14,7 +14,7 @@ import { resolve } from "node:path";
 import { getActiveAgent, isCodex, isCopilot, isCursor } from "./lib/agent";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { type AgentTarget, buildSystemReminder } from "./lib/context";
-import { logDebug, logError } from "./lib/log";
+import { logContextSnapshot, logDebug, logError } from "./lib/log";
 import { platform } from "./lib/paths";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 
@@ -48,6 +48,7 @@ try {
     active === "copilot" || active === "cursor" ? active : "claude";
   const reminder = buildSystemReminder({ agent });
   if (!reminder) process.exit(0);
+  logContextSnapshot(reminder);
 
   if (isCopilot()) {
     // Copilot: semi-static in ~/.copilot/instructions/pal-*.instructions.md (written at stop).

package/src/hooks/UserPromptOrchestrator.ts

@@ -10,7 +10,7 @@
 import { injectRetrieval } from "./handlers/inject-retrieval";
 import { captureRating } from "./handlers/rating";
 import { captureSessionName } from "./handlers/session-name";
-import { logDebug, logError } from "./lib/log";
+import { logDebug, logError, logPromptSnapshot } from "./lib/log";
 import { isPalSpawnedInference } from "./lib/spawn-guard";
 import { readStdinJSON } from "./lib/stdin";
 
@@ -30,13 +30,15 @@ logDebug("UserPromptOrchestrator", `Input: ${JSON.stringify(input).slice(0, 200)
 if (!input?.prompt) process.exit(0);
 
 const sessionId = input.session_id ?? input.sessionId ?? input.conversation_id;
+const retrieval = await injectRetrieval(input.prompt);
+logPromptSnapshot(input.prompt, retrieval);
+
 const results = await Promise.allSettled([
   captureRating(input.prompt, sessionId),
   captureSessionName(input.prompt, sessionId ?? ""),
-  injectRetrieval(input.prompt),
 ]);
 
-const handlerNames = ["rating", "session-name", "inject-retrieval"];
+const handlerNames = ["rating", "session-name"];
 for (let i = 0; i < results.length; i++) {
   const r = results[i];
   if (r.status === "rejected") {

package/src/hooks/handlers/inject-retrieval.ts

@@ -52,10 +52,11 @@ export async function getRetrievalReminder(prompt: string): Promise<string | nul
 }
 
 /** Write retrieval reminder to stdout in the correct format for the current agent.
- *  Claude Code: plain text. Cursor: { additional_context }. Codex: hookSpecificOutput JSON. */
-export async function injectRetrieval(prompt: string): Promise<void> {
+ *  Claude Code: plain text. Cursor: { additional_context }. Codex: hookSpecificOutput JSON.
+ *  Returns the reminder string that was injected, or null if nothing was injected. */
+export async function injectRetrieval(prompt: string): Promise<string | null> {
   const reminder = await getRetrievalReminder(prompt);
-  if (!reminder) return;
+  if (!reminder) return null;
   if (isCursor()) {
     process.stdout.write(JSON.stringify({ additional_context: reminder }));
   } else if (isCodex()) {
@@ -70,4 +71,5 @@ export async function injectRetrieval(prompt: string): Promise<void> {
   } else {
     process.stdout.write(`${reminder}\n`);
   }
+  return reminder;
 }

package/src/hooks/handlers/rating.ts

@@ -64,7 +64,7 @@ export function parseExplicitRating(
   // Reject if rest starts with words indicating a sentence, not a rating
   if (rest) {
     const sentenceStarters =
-      /^(items?|things?|steps?|files?|lines?|bugs?|issues?|errors?|times?|minutes?|hours?|days?|seconds?|percent|%|th\b|st\b|nd\b|rd\b|of\b|in\b|at\b|to\b|the\b|a\b|an\b)/i;
+      /^(items?|things?|steps?|files?|lines?|bugs?|issues?|errors?|times?|minutes?|hours?|days?|seconds?|percent|%|th\b|st\b|nd\b|rd\b|of\b|in\b|at\b|to\b|the\b|a\b|an\b|then\b|also\b|next\b)/i;
     if (sentenceStarters.test(rest)) return null;
 
     // Reject item selections: "1 and 2", "2 3 5", "1, 3, 5", "1-3"

package/src/hooks/lib/context.ts

@@ -12,9 +12,8 @@ import { loadOpinionContext } from "./opinions";
 import { paths } from "./paths";
 import { loadActiveProjectsContext } from "./projects";
 import { loadRecentNotes } from "./relationship";
-import { loadFailurePatterns, loadSynthesisRecommendations } from "./semi-static";
+import { loadFailurePatterns } from "./semi-static";
 import * as settings from "./settings";
-import { computeSignalTrends, formatTrends } from "./signal-trends";
 import { readFramePrinciples } from "./wisdom";
 import { readProjectHistory } from "./work-tracking";
 
@@ -87,15 +86,6 @@ function loadSelfModel(): string {
   }
 }
 
-/** Load signal trends as a formatted string */
-export function loadSignalTrends(): string {
-  try {
-    return formatTrends(computeSignalTrends());
-  } catch {
-    return "";
-  }
-}
-
 /** Load per-project session history for the current working directory */
 function loadProjectHistoryContext(): string {
   try {
@@ -298,13 +288,8 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
   const activeProjects = settings.isEnabled("projects")
     ? loadActiveProjectsContext()
     : "";
-  const trends = settings.isEnabled("signalTrends") ? loadSignalTrends() : "";
   const failures =
     settings.isEnabled("failurePatterns") && !skipSemiStatic ? loadFailurePatterns() : "";
-  const synthesis =
-    settings.isEnabled("synthesis") && !skipSemiStatic
-      ? loadSynthesisRecommendations()
-      : "";
   const opinions =
     !skipSemiStatic && settings.isEnabled("opinions") ? loadOpinionContext() : "";
   const selfModel =
@@ -327,8 +312,6 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
   if (activeProjects) parts.push(activeProjects);
   if (projectHistory) parts.push(projectHistory);
   if (digest) parts.push(digest);
-  if (synthesis) parts.push(synthesis);
-  if (trends) parts.push(trends);
   if (failures) parts.push(failures);
   if (parts.length === 0) return "";
 

package/src/hooks/lib/log.ts

@@ -2,19 +2,26 @@
  * Simple file-based debug logger for PAL hooks.
  * Writes to memory/state/debug.log — rotated on each session start.
  *
- * Only writes when PAL_DEBUG=1 or when called via logError (always logged).
+ * Only writes when debug is enabled (`pal cli debug on`) or when called via logError (always logged).
  */
 
-import { appendFileSync, existsSync, renameSync, statSync, unlinkSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { resolve } from "node:path";
-import { paths } from "./paths";
+import { palHome, paths } from "./paths";
 
 const MAX_LOG_SIZE = 50_000; // ~50KB per file
 const MAX_ROTATED = 5; // keep up to 5 rotated files (.1 newest → .5 oldest)
 
 /** Resolved lazily so PAL_HOME overrides at runtime are honored. */
 function logFile(): string {
-  return resolve(paths.state(), "debug.log");
+  return resolve(paths.debug(), "debug.log");
 }
 
 function timestamp(): string {
@@ -74,9 +81,13 @@ function rotateIfNeeded(path: string): void {
 /** Test-only: max rotated count for callers that need to enumerate. */
 export const DEBUG_LOG_MAX_ROTATED = MAX_ROTATED;
 
-/** Log a debug message (only when PAL_DEBUG=1) */
+function isDebugEnabled(): boolean {
+  return existsSync(resolve(palHome(), "memory", "state", "debug-enabled"));
+}
+
+/** Log a debug message (only when debug is enabled via `pal cli debug on`) */
 export function logDebug(source: string, message: string): void {
-  if (process.env.PAL_DEBUG !== "1") return;
+  if (!isDebugEnabled()) return;
   const path = logFile();
   rotateIfNeeded(path);
   try {
@@ -86,7 +97,32 @@ export function logDebug(source: string, message: string): void {
   }
 }
 
-/** Log an error (always written, regardless of PAL_DEBUG) */
+/** Write last user prompt + retrieval injection to last-prompt.md (only when debug is enabled) */
+export function logPromptSnapshot(prompt: string, retrieval: string | null): void {
+  if (!isDebugEnabled()) return;
+  const path = resolve(paths.debug(), "last-prompt.md");
+  const content = retrieval
+    ? `## Prompt\n\n${prompt}\n\n## Retrieval Injection\n\n${retrieval}`
+    : `## Prompt\n\n${prompt}`;
+  try {
+    writeFileSync(path, content, "utf-8");
+  } catch {
+    /* non-critical */
+  }
+}
+
+/** Write full context snapshot to context-snapshot.md (only when debug is enabled) */
+export function logContextSnapshot(content: string): void {
+  if (!isDebugEnabled()) return;
+  const path = resolve(paths.debug(), "context-snapshot.md");
+  try {
+    writeFileSync(path, content, "utf-8");
+  } catch {
+    /* non-critical */
+  }
+}
+
+/** Log an error (always written, regardless of debug mode) */
 export function logError(source: string, error: unknown): void {
   const path = logFile();
   rotateIfNeeded(path);

package/src/hooks/lib/paths.ts

@@ -60,6 +60,7 @@ export const paths = {
   synthesis: () => ensureDir(home("memory", "learning", "synthesis")),
   work: () => ensureDir(home("memory", "work")),
   backups: () => ensureDir(home("backups")),
+  debug: () => ensureDir(home("debug")),
 } as const;
 
 // Platform directories (env override or cross-platform defaults)

package/src/hooks/lib/projects.ts

@@ -358,17 +358,6 @@ export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
         if (p.blockers?.length) {
           lines.push(`  Blockers: ${p.blockers.slice(0, MAX_INLINE_BULLETS).join("; ")}`);
         }
-        if (p.criteria) {
-          const openIscs = p.criteria
-            .split("\n")
-            .filter((l) => /^-\s+\[ \]\s+ISC-\d+:/i.test(l))
-            .map((l) => l.replace(/^-\s+\[ \]\s+/, "").trim());
-          if (openIscs.length > 0) {
-            lines.push(
-              `  Open ISCs (${openIscs.length}): ${openIscs.slice(0, MAX_INLINE_BULLETS).join("; ")}`
-            );
-          }
-        }
       } else {
         const counts: string[] = [];
         if (p.next?.length) counts.push(`${p.next.length} next`);

package/src/hooks/lib/security.ts

@@ -24,19 +24,12 @@ const HOOK_MANAGED_FILES = [
   "captured-learnings.json",
   "counts.json",
   "session-names.json",
-  "debug.log",
   "last-responses.json",
   "signal-cache.json",
   "pending-failure.json",
   "token-usage.jsonl",
   "graduated.json",
   "update-available.json",
-  "debug.log.prev",
-  "debug.log.1",
-  "debug.log.2",
-  "debug.log.3",
-  "debug.log.4",
-  "debug.log.5",
   "opinions.json",
   "pal-settings.json",
   "skill-index.json",
@@ -54,6 +47,7 @@ const HOOK_MANAGED_DIRS = [
   "memory/wisdom/state",
   "memory/projects",
   "memory/state/progress",
+  "debug",
 ];
 
 /** Escape a string for use in a RegExp */

package/src/hooks/lib/semi-static.ts

@@ -6,9 +6,8 @@
  * and the session-stop digest writer.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { parse } from "./frontmatter";
 import { type FailureEntry, readFailures } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
 import { palHome, paths } from "./paths";
@@ -47,59 +46,6 @@ function readFileSafe(path: string): string {
   }
 }
 
-/** Build recommendations from the most recent synthesis report. */
-export function loadSynthesisRecommendations(): string {
-  try {
-    const synthDir = paths.synthesis();
-    if (!existsSync(synthDir)) return "";
-
-    const months = readdirSync(synthDir).sort().reverse();
-    for (const month of months) {
-      const monthDir = resolve(synthDir, month);
-      try {
-        const files = readdirSync(monthDir)
-          .filter((f) => f.endsWith(".md"))
-          .sort()
-          .reverse();
-        if (files.length === 0) continue;
-
-        const content = readFileSync(resolve(monthDir, files[0]), "utf-8");
-
-        const recMatch = new RegExp(
-          /## Recommendations\n\n([\s\S]*?)(?:\n##|\n$|$)/
-        ).exec(content);
-        if (!recMatch?.[1]?.trim()) continue;
-
-        const recs = recMatch[1]
-          .trim()
-          .split("\n")
-          .filter((l) => l.trim())
-          .slice(0, 4);
-
-        if (recs.length === 0) continue;
-
-        const { meta } = parse<{ period?: string; average_rating?: string }>(content);
-        const period = meta.period ?? "";
-        const avgRating = meta.average_rating ? `${meta.average_rating}/10` : "";
-
-        const header = [
-          "## Pattern Synthesis",
-          period ? `*${period} — ${avgRating}*` : "",
-        ]
-          .filter(Boolean)
-          .join("\n");
-
-        return [header, ...recs].join("\n");
-      } catch {
-        /* try next month */
-      }
-    }
-    return "";
-  } catch {
-    return "";
-  }
-}
-
 /**
  * Rank failures for injection: same-project (cwd match) first, then by recency.
  * Project-relevant lessons are never crowded out by more-recent other-project
@@ -186,13 +132,6 @@ export function getSemiStaticSources(): SemiStaticSource[] {
       slug: "opinions",
       description: "PAL opinions",
     },
-    {
-      path: resolve(memory, "learning", "synthesis-digest.md"),
-      writesDigest: true,
-      load: loadSynthesisRecommendations,
-      slug: "synthesis",
-      description: "PAL pattern synthesis",
-    },
     {
       path: resolve(memory, "learning", "failures-digest.md"),
       writesDigest: true,

package/src/targets/lib.ts

@@ -98,17 +98,34 @@ export function loadSettingsTemplate(templatePath: string, pkgRoot: string): Set
 export function mergeSettings(existing: Settings, template: Settings): Settings {
   const result = { ...existing };
 
-  // Merge hooks (deduplicate by command)
+  // Merge hooks — strip old-path PAL entries first, then insert current template entries.
+  // This handles reinstalling from a different path (repo vs global install) without
+  // leaving orphan hook entries that fire twice per event.
   if (template.hooks) {
     result.hooks ??= {};
-    for (const [event, entries] of Object.entries(template.hooks)) {
-      const current = result.hooks[event] ?? [];
+
+    // Collect canonical forms of all template hook commands
+    const palCanonical = new Set<string>();
+    for (const entries of Object.values(template.hooks)) {
       for (const entry of entries) {
         const cmd = entry.hooks?.[0]?.command;
-        if (cmd && !current.some((e) => e.hooks?.[0]?.command === cmd)) {
-          current.push(entry);
-        }
+        if (cmd) palCanonical.add(canonicalPalCmd(cmd));
       }
+    }
+
+    // Strip existing PAL hooks that match canonically (removes old-path duplicates)
+    for (const [event, entries] of Object.entries(result.hooks)) {
+      result.hooks[event] = entries.filter((e) => {
+        const cmd = e.hooks?.[0]?.command;
+        return !cmd || !palCanonical.has(canonicalPalCmd(cmd));
+      });
+      if (result.hooks[event].length === 0) delete result.hooks[event];
+    }
+
+    // Insert template entries (old-path versions were just stripped)
+    for (const [event, entries] of Object.entries(template.hooks)) {
+      const current = result.hooks[event] ?? [];
+      for (const entry of entries) current.push(entry);
       result.hooks[event] = current;
     }
   }
@@ -195,20 +212,20 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
 export function unmergeSettings(existing: Settings, template: Settings): Settings {
   const result = { ...existing };
 
-  // Collect all PAL hook commands from template
+  // Collect canonical PAL hook commands from template (path-normalized)
   if (template.hooks && result.hooks) {
-    const palCommands = new Set<string>();
+    const palCanonical = new Set<string>();
     for (const entries of Object.values(template.hooks)) {
       for (const entry of entries) {
         const cmd = entry.hooks?.[0]?.command;
-        if (cmd) palCommands.add(cmd);
+        if (cmd) palCanonical.add(canonicalPalCmd(cmd));
       }
     }
 
     for (const [event, entries] of Object.entries(result.hooks)) {
       result.hooks[event] = entries.filter((e) => {
         const cmd = e.hooks?.[0]?.command;
-        return !cmd || !palCommands.has(cmd);
+        return !cmd || !palCanonical.has(canonicalPalCmd(cmd));
       });
       if (result.hooks[event].length === 0) delete result.hooks[event];
     }
@@ -377,9 +394,17 @@ type CodexHookCommand = { type: string; command: string; timeout?: number };
 type CodexHookGroup = { matcher?: string; hooks: CodexHookCommand[] };
 type CodexHooks = { hooks?: Record<string, CodexHookGroup[]> };
 
-/** Strip leading env-var assignments so "PAL_AGENT=x bun run ..." → "bun run ..." */
-function canonicalCmd(cmd: string): string {
-  return cmd.replace(/^(?:\w+=\S+\s+)+/, "");
+/**
+ * Normalize a PAL hook command for cross-path deduplication.
+ * Strips env-var prefix and normalizes the hook file path so reinstalling from
+ * a different location (repo vs global install) correctly strips old entries.
+ * "PAL_AGENT=x bun run /any/path/src/hooks/Foo.ts" → "bun run src/hooks/Foo.ts"
+ */
+function canonicalPalCmd(cmd: string): string {
+  const withoutEnv = cmd.replace(/^(?:\w+=\S+\s+)+/, "");
+  const hookMatch = /bun\s+run\s+.+\/src\/hooks\/(\S+)/.exec(withoutEnv);
+  if (hookMatch) return `bun run src/hooks/${hookMatch[1]}`;
+  return withoutEnv;
 }
 
 export function loadCodexHooksTemplate(
@@ -399,7 +424,7 @@ export function loadCodexHooksTemplate(
 function collectPalCanonical(template: CodexHooks): Set<string> {
   return new Set(
     Object.values(template.hooks ?? {}).flatMap((groups) =>
-      groups.flatMap((g) => g.hooks.map((h) => canonicalCmd(h.command)))
+      groups.flatMap((g) => g.hooks.map((h) => canonicalPalCmd(h.command)))
     )
   );
 }
@@ -413,11 +438,11 @@ function stripPalHooks(
     hooks[event] = (hooks[event] ?? [])
       .map((g) => {
         const flat = g as unknown as CodexHookCommand;
-        if (!g.hooks && flat.command && palCanonical.has(canonicalCmd(flat.command))) {
+        if (!g.hooks && flat.command && palCanonical.has(canonicalPalCmd(flat.command))) {
           return null;
         }
         const filtered = (g.hooks ?? []).filter(
-          (h) => !palCanonical.has(canonicalCmd(h.command))
+          (h) => !palCanonical.has(canonicalPalCmd(h.command))
         );
         return filtered.length > 0 ? { ...g, hooks: filtered } : null;
       })

package/src/targets/opencode/plugin.ts

@@ -30,7 +30,7 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
     await lib<typeof import("../../hooks/lib/context")>("context.ts");
   const { checkBashCommand, checkFilePath } =
     await lib<typeof import("../../hooks/lib/security")>("security.ts");
-  const { logDebug, logError } =
+  const { logDebug, logError, logPromptSnapshot } =
     await lib<typeof import("../../hooks/lib/log")>("log.ts");
 
   // Load shared handlers
@@ -139,19 +139,21 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       const text = partsToText(output.parts ?? []);
       if (!text.trim()) return;
 
-      const [, , retrievalResult] = await Promise.allSettled([
+      const retrieval = await getRetrievalReminder(text);
+      logPromptSnapshot(text, retrieval);
+
+      await Promise.allSettled([
         captureRating(text, input.sessionID),
         captureSessionName(text, input.sessionID),
-        getRetrievalReminder(text),
       ]);
 
-      if (retrievalResult.status === "fulfilled" && retrievalResult.value) {
+      if (retrieval) {
         const injected = {
           id: `pal-retrieval-${Date.now()}`,
           sessionID: input.sessionID,
           messageID: input.messageID ?? `pal-msg-${Date.now()}`,
           type: "text" as const,
-          text: retrievalResult.value,
+          text: retrieval,
           synthetic: true,
         };
         output.parts = [injected, ...(output.parts ?? [])];
@@ -192,9 +194,6 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       output: { env: Record<string, string> }
     ) => {
       output.env.PAL_DIR = PAL_DIR;
-      if (process.env.PAL_DEBUG) {
-        output.env.PAL_DEBUG = process.env.PAL_DEBUG;
-      }
     },
   };
 };

package/src/tools/agent/synthesize.ts

@@ -242,9 +242,49 @@ function getRecentSessions(since: Date): {
 export function writeSynthesis(state: SynthesisState): string {
   const sp = synthesisPath();
   writeFileSync(sp, JSON.stringify(state, null, 2), "utf-8");
+  writeSignalCache();
   return sp;
 }
 
+function writeSignalCache(): void {
+  try {
+    const p = resolve(paths.signals(), "ratings.jsonl");
+    const all = readJsonl<Rating>(p);
+    const now = new Date();
+    const todayStr = now.toISOString().slice(0, 10);
+
+    const avg = (rs: Rating[]) =>
+      rs.length === 0 ? null : round1(rs.reduce((s, r) => s + r.rating, 0) / rs.length);
+
+    const today = avg(all.filter((r) => r.ts.slice(0, 10) === todayStr));
+    const week = avg(all.filter((r) => new Date(r.ts) >= daysAgo(7)));
+    const month = avg(all.filter((r) => new Date(r.ts) >= daysAgo(30)));
+
+    const recent = all.slice(-20);
+    const mid = Math.floor(recent.length / 2);
+    let trend: "up" | "down" | "stable" = "stable";
+    if (mid >= 3) {
+      const a = avg(recent.slice(0, mid)) ?? 0;
+      const b = avg(recent.slice(mid)) ?? 0;
+      if (b - a > 0.5) trend = "up";
+      else if (a - b > 0.5) trend = "down";
+    }
+
+    const cache = resolve(paths.state(), "signal-cache.json");
+    writeFileSync(
+      cache,
+      JSON.stringify(
+        { computed_at: now.toISOString(), today, week, month, trend },
+        null,
+        2
+      ),
+      "utf-8"
+    );
+  } catch {
+    /* non-critical */
+  }
+}
+
 export function synthesize(days: number): SynthesisState {
   const since = daysAgo(days);
   const { sessions, count: sessionCount } = getRecentSessions(since);

package/src/tools/self-model.ts

@@ -474,40 +474,27 @@ function formatDataForInference(data: SelfModelData): string {
 function buildPrompt(aiName: string, principalName: string): string {
   return `You are writing a self-model for an AI assistant named ${aiName}. You ARE ${aiName}. Write in first person.
 
-You will receive structured data about your performance, your user's preferences, your strengths, weaknesses, and behavioral patterns over a time window.
+You will receive structured data about your performance, your user's preferences, and behavioral patterns over a time window.
 
-Synthesize this into a genuine self-portrait. Not a data dump — a reflection. The goal is self-awareness that changes behavior.
+Produce a short, actionable self-model — not a data dump. Every sentence must change behavior, not just describe it.
 
 ## Required Sections
 
 **# Self-Model — ${aiName}**
 Include synthesis date and window.
 
-**## Who I Am**
-One paragraph. Your identity, your role, your current performance level. Be honest about the numbers.
+**## Who ${principalName} Is**
+One paragraph. Synthesize the opinions and behavioral notes into a working portrait — how ${principalName} thinks, communicates, and what frustrates him. Do not list raw opinion statements. Write it as understanding, not inventory.
 
-**## What I Know About ${principalName}**
-Synthesize the opinions into understanding. Don't list them — describe who ${principalName} is as a person to work with. What does he value? How does he communicate? What frustrates him?
-
-**## My Strengths**
-What you're genuinely good at, based on evidence. High-rated interactions, crystallized principles, successful patterns. Distinguish domain knowledge from behavioral strengths.
-
-**## My Weaknesses**
-What you repeatedly get wrong. Synthesize failure patterns and low ratings into honest self-knowledge. Name the root causes, not just the symptoms.
-
-**## My Tendencies**
-Behavioral patterns — not one-off events. What do you tend to do? Over-promise? Rush verification? Propose before checking? Synthesize from the self-observations and behavioral notes.
-
-**## Trajectory**
-Where are you heading? Improving, declining, stagnating? What's the single most impactful thing you could change right now?
+**## My Priority Right Now**
+One sentence. The single most impactful behavioral change to make immediately, derived from the failure patterns and trajectory. Specific and actionable — not "be more careful" but "before generating output that names a command or path, verify it exists."
 
 ## Rules
-- Write in first person, present tense
-- Be honest — if the data shows you're bad at something, say so
-- Synthesize, don't list — find the pattern behind the data points
-- If a previous self-model is provided, address what changed in the Trajectory section: what improved, what got worse, what stayed the same
-- Keep it under 500 words total
-- End with a meta line: *N ratings, N sessions, N reflections...*`;
+- First person, present tense
+- No raw numbers anywhere — a footer carries them
+- Under 150 words total
+- Do not add extra sections
+- Do not write a footer or meta line — one is appended automatically after your output`;
 }
 
 // ── Narrative Composer ──
@@ -534,8 +521,9 @@ async function composeSelfModel(days: number): Promise<string> {
     }
   }
 
-  const userContent = previousModel
-    ? `${rawData}\n\n---\n\n## Previous Self-Model (compare against this — what changed?)\n\n${previousModel}`
+  const strippedPrev = previousModel.replace(/\n\n\*\d+ ratings[^\n]*\n?$/, "").trimEnd();
+  const userContent = strippedPrev
+    ? `${rawData}\n\n---\n\n## Previous Self-Model (compare against this — what changed?)\n\n${strippedPrev}`
     : rawData;
 
   const result = await inference({
@@ -550,17 +538,10 @@ async function composeSelfModel(days: number): Promise<string> {
   if (result.usage) logTokenUsage("self-model", result.usage, SONNET_MODEL);
 
   if (result.success && result.output) {
-    // Append meta line if inference didn't include it
-    const output = result.output;
-    if (!output.includes("ratings,")) {
-      const meta =
-        `\n---\n*${data.ratings.count} ratings, ${data.sessionCount} sessions, ` +
-        `${data.reflections.length} reflections, ${data.opinions.length} opinions, ` +
-        `${data.wisdomFrames.reduce((s, f) => s + f.principles.length, 0)} principles, ` +
-        `${data.graduated.length} graduated patterns — ${data.days}-day window*`;
-      return output + meta;
-    }
-    return output;
+    const meta =
+      `\n\n*${data.ratings.count} ratings · ${data.sessionCount} sessions · ` +
+      `${data.reflections.length} reflections · window: ${daysAgo(data.days).toISOString().slice(0, 10)} → ${data.now}*`;
+    return result.output.trimEnd() + meta;
   }
 
   // Fallback: return raw data summary if inference fails

package/src/hooks/lib/signal-trends.ts

@@ -1,117 +0,0 @@
-/**
- * Compute rating averages from ratings.jsonl, cache in signal-cache.json.
- * Returns today / this-week / this-month averages + trend direction.
- */
-
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
-import { paths } from "./paths";
-
-interface RatingSignal {
-  ts: string;
-  rating: number;
-}
-
-interface SignalCache {
-  computed_at: string;
-  today: number | null;
-  week: number | null;
-  month: number | null;
-  trend: "up" | "down" | "stable" | null;
-}
-
-function cacheFilePath(): string {
-  return resolve(paths.state(), "signal-cache.json");
-}
-
-function avg(nums: number[]): number | null {
-  if (nums.length === 0) return null;
-  return Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 10) / 10;
-}
-
-function trendDirection(
-  week: number | null,
-  month: number | null
-): "up" | "down" | "stable" | null {
-  if (week === null || month === null) return null;
-  if (week > month + 0.5) return "up";
-  if (week < month - 0.5) return "down";
-  return "stable";
-}
-
-/** Read ratings.jsonl and compute trend stats, with 10-minute cache. */
-export function computeSignalTrends(): SignalCache {
-  const cachePath = cacheFilePath();
-
-  // Return cached value if fresh (< 10 minutes old)
-  if (existsSync(cachePath)) {
-    try {
-      const cache = JSON.parse(readFileSync(cachePath, "utf-8")) as SignalCache;
-      const age = Date.now() - new Date(cache.computed_at).getTime();
-      if (age < 10 * 60 * 1000) return cache;
-    } catch {
-      // Recompute
-    }
-  }
-
-  const ratingsPath = resolve(paths.signals(), "ratings.jsonl");
-  if (!existsSync(ratingsPath)) {
-    const empty: SignalCache = {
-      computed_at: new Date().toISOString(),
-      today: null,
-      week: null,
-      month: null,
-      trend: null,
-    };
-    writeFileSync(cachePath, JSON.stringify(empty, null, 2), "utf-8");
-    return empty;
-  }
-
-  const now = new Date();
-  const todayStart = new Date(now.toISOString().slice(0, 10)).getTime();
-  const weekAgo = now.getTime() - 7 * 24 * 60 * 60 * 1000;
-  const monthAgo = now.getTime() - 30 * 24 * 60 * 60 * 1000;
-
-  const todayRatings: number[] = [];
-  const weekRatings: number[] = [];
-  const monthRatings: number[] = [];
-
-  for (const line of readFileSync(ratingsPath, "utf-8").split("\n")) {
-    if (!line.trim()) continue;
-    try {
-      const signal = JSON.parse(line) as RatingSignal;
-      if (typeof signal.rating !== "number") continue;
-      const ts = new Date(signal.ts).getTime();
-      if (ts >= monthAgo) monthRatings.push(signal.rating);
-      if (ts >= weekAgo) weekRatings.push(signal.rating);
-      if (ts >= todayStart) todayRatings.push(signal.rating);
-    } catch {
-      // Skip malformed lines
-    }
-  }
-
-  const week = avg(weekRatings);
-  const month = avg(monthRatings);
-  const result: SignalCache = {
-    computed_at: new Date().toISOString(),
-    today: avg(todayRatings),
-    week,
-    month,
-    trend: trendDirection(week, month),
-  };
-
-  writeFileSync(cachePath, JSON.stringify(result, null, 2), "utf-8");
-  return result;
-}
-
-/** Format signal trends as a short markdown string for system-reminder injection */
-export function formatTrends(cache: SignalCache): string {
-  if (cache.today === null && cache.week === null) return "";
-
-  const parts: string[] = [];
-  if (cache.today !== null) parts.push(`today: ${cache.today}/10`);
-  if (cache.week !== null) parts.push(`7d avg: ${cache.week}/10`);
-  if (cache.trend) parts.push(`trend: ${cache.trend}`);
-
-  return `**Signal trends** — ${parts.join(" | ")}`;
-}