portable-agent-layer 0.51.2 → 0.53.0

package/src/hooks/lib/context.ts

@@ -6,15 +6,16 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
+import { loadAnalyzeNudge } from "./analyze-nudge";
 import { readLearnings } from "./learning-store";
 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 +88,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 +290,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 =
@@ -315,10 +302,14 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
   const handoff = settings.isEnabled("handoff") ? loadHandoff() : "";
   // Maintainer-only: self-gates to a repo checkout, "" for everyone else.
   const algoReview = loadAlgorithmReviewNudge();
+  const reflectNudge = loadReflectNudge();
+  const analyzeNudge = loadAnalyzeNudge();
   const parts: string[] = [];
   if (startup) parts.push(startup);
   if (handoff) parts.push(handoff);
   if (algoReview) parts.push(algoReview);
+  if (reflectNudge) parts.push(reflectNudge);
+  if (analyzeNudge) parts.push(analyzeNudge);
   if (selfModel) parts.push(selfModel);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);
@@ -327,8 +318,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

@@ -5,7 +5,14 @@
  * 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 { palHome, paths } from "./paths";
 
@@ -14,7 +21,7 @@ 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 {
@@ -90,6 +97,31 @@ export function logDebug(source: string, message: string): void {
   }
 }
 
+/** 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();

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 ?? [])];

package/src/tools/agent/analyze.ts

@@ -9,6 +9,7 @@
  */
 
 import { parseArgs } from "node:util";
+import { writeLastAnalyzeDate } from "../../hooks/lib/analyze-nudge";
 import { type AnalysisResult, analyze } from "../../hooks/lib/graduation";
 
 // ── ANSI Colors ──
@@ -23,7 +24,7 @@ const c = {
   magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
 };
 
-export function printReport(result: AnalysisResult): void {
+function printReport(result: AnalysisResult): void {
   const hasPatterns = result.candidates.length > 0 || result.emerging.length > 0;
   const hasRatings = result.ratings !== null;
 
@@ -117,9 +118,9 @@ export function printReport(result: AnalysisResult): void {
   }
 }
 
-async function run() {
+export async function run(argv: string[] = Bun.argv.slice(2)) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       help: { type: "boolean", short: "h" },
       actionable: { type: "boolean", short: "a" },
@@ -145,13 +146,14 @@ async function run() {
   To crystallize a graduated pattern, add it to the target wisdom frame:
     - Your principle here [CRYSTAL: 85%]
 
-  Usage: bun run tool:analyze [--actionable] [--help]
+  Usage: pal cli analyze [--actionable]
 `);
     process.exit(0);
   }
 
   const result = await analyze({ actionable: values.actionable });
   printReport(result);
+  writeLastAnalyzeDate(new Date().toISOString());
 }
 
 if (import.meta.main) await run();

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

@@ -1,12 +1,19 @@
 #!/usr/bin/env bun
 /**
- * RelationshipNote — Write a B entry to today's relationship log.
+ * RelationshipNote — Write W/O/Session entries to today's relationship log.
  *
- * Called in the ALGORITHM LEARN phase. Claude writes the B entry directly
- * from full session context — no inference call needed.
+ * Called in the ALGORITHM LEARN phase. Writes behavioral observations about
+ * the user (O, W) and session diary entries (--b).
  *
  * Usage:
- *   bun ~/.pal/tools/relationship-note.ts --b "what I did this session"
+ *   bun ~/.pal/tools/relationship-note.ts --o "Rico prefers X" --confidence 0.80
+ *   bun ~/.pal/tools/relationship-note.ts --w "Rico is building X in TypeScript"
+ *   bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
+ *
+ * Note types:
+ *   --o   Opinion/behavioral observation about the user (requires --confidence)
+ *   --w   World fact about the user's situation (objective, observable)
+ *   --b   Session diary — what Jarvis did this session (first-person, specific)
  */
 
 import { parseArgs } from "node:util";
@@ -16,35 +23,72 @@ function run() {
   const { values } = parseArgs({
     args: Bun.argv.slice(2),
     options: {
+      o: { type: "string", multiple: true },
+      w: { type: "string", multiple: true },
       b: { type: "string" },
+      confidence: { type: "string" },
       help: { type: "boolean", short: "h" },
     },
   });
 
   if (values.help) {
     console.log(`
-RelationshipNote — Append a B entry to today's relationship log
+RelationshipNote — Append W/O/Session entries to today's relationship log
 
 Usage:
-  bun ~/.pal/tools/relationship-note.ts --b "description"
+  bun ~/.pal/tools/relationship-note.ts --o "Rico prefers X" --confidence 0.80
+  bun ~/.pal/tools/relationship-note.ts --w "Rico is building X in TypeScript"
+  bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
+
+Flags:
+  --o TEXT          Opinion/behavioral observation about the user
+  --confidence N    Confidence for --o (0.0–1.0, default 0.75)
+  --w TEXT          World fact about the user's situation
+  --b TEXT          Session diary — what Jarvis did (first-person, specific)
 
-Arguments:
-  --b   What happened this session (1-2 sentences, first-person, specific)
+Multiple flags may be combined in one call. At least one of --o, --w, --b is required.
 
 Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
 `);
     process.exit(0);
   }
 
-  if (!values.b) {
-    console.error("Required: --b");
+  if (!values.o && !values.w && !values.b) {
+    console.error("Required: at least one of --o, --w, --b");
     process.exit(1);
   }
 
-  appendNotes([{ type: "Session", text: values.b }]);
+  const notes = [];
+
+  if (values.o && values.o.length > 0) {
+    const confidence = values.confidence ? Number.parseFloat(values.confidence) : 0.75;
+    if (Number.isNaN(confidence) || confidence < 0 || confidence > 1) {
+      console.error("--confidence must be a number between 0.0 and 1.0");
+      process.exit(1);
+    }
+    for (const text of values.o) {
+      notes.push({ type: "O" as const, text, confidence });
+    }
+  }
+
+  if (values.w && values.w.length > 0) {
+    for (const text of values.w) {
+      notes.push({ type: "W" as const, text });
+    }
+  }
+
+  if (values.b) {
+    notes.push({ type: "Session" as const, text: values.b });
+  }
+
+  appendNotes(notes);
 
   console.log(
-    JSON.stringify({ success: true, message: "Relationship note written" }, null, 2)
+    JSON.stringify(
+      { success: true, message: "Relationship note written", count: notes.length },
+      null,
+      2
+    )
   );
 }
 

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