portable-agent-layer 0.40.0 → 0.41.1

package/src/hooks/lib/log.ts

@@ -5,35 +5,82 @@
  * Only writes when PAL_DEBUG=1 or when called via logError (always logged).
  */
 
-import { appendFileSync, existsSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, renameSync, statSync, unlinkSync } from "node:fs";
 import { resolve } from "node:path";
 import { paths } from "./paths";
 
-const LOG_FILE = resolve(paths.state(), "debug.log");
-const MAX_LOG_SIZE = 50_000; // ~50KB, then rotate
+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");
+}
 
 function timestamp(): string {
   return new Date().toISOString().replace("T", " ").slice(0, 19);
 }
 
-function rotateIfNeeded(): void {
+/**
+ * Rotate debug.log when it exceeds MAX_LOG_SIZE.
+ *
+ * Keeps up to MAX_ROTATED rotated files numbered .1 (newest) through
+ * .MAX_ROTATED (oldest). Each rotation shifts .N-1 → .N, drops the oldest,
+ * and renames the current log to .1. Total disk footprint bounded at
+ * (MAX_ROTATED + 1) * MAX_LOG_SIZE ≈ 300KB.
+ *
+ * Migrates legacy .prev → .1 on first new rotation so existing history
+ * survives the format change.
+ */
+function rotateIfNeeded(path: string): void {
   try {
-    if (existsSync(LOG_FILE) && statSync(LOG_FILE).size > MAX_LOG_SIZE) {
-      const prev = `${LOG_FILE}.prev`;
-      writeFileSync(prev, "");
-      renameSync(LOG_FILE, prev);
+    if (!existsSync(path) || statSync(path).size <= MAX_LOG_SIZE) return;
+    // Backward-compat migration: legacy .prev was the single old rotation file.
+    const legacyPrev = `${path}.prev`;
+    if (existsSync(legacyPrev) && !existsSync(`${path}.1`)) {
+      try {
+        renameSync(legacyPrev, `${path}.1`);
+      } catch {
+        /* ignore */
+      }
+    }
+    // Drop the oldest, then shift .N-1 → .N for N from MAX_ROTATED down to 2.
+    const oldest = `${path}.${MAX_ROTATED}`;
+    if (existsSync(oldest)) {
+      try {
+        unlinkSync(oldest);
+      } catch {
+        /* ignore */
+      }
     }
+    for (let i = MAX_ROTATED - 1; i >= 1; i--) {
+      const src = `${path}.${i}`;
+      const dst = `${path}.${i + 1}`;
+      if (existsSync(src)) {
+        try {
+          renameSync(src, dst);
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+    // Finally, current → .1
+    renameSync(path, `${path}.1`);
   } catch {
     /* non-critical */
   }
 }
 
+/** 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) */
 export function logDebug(source: string, message: string): void {
   if (process.env.PAL_DEBUG !== "1") return;
-  rotateIfNeeded();
+  const path = logFile();
+  rotateIfNeeded(path);
   try {
-    appendFileSync(LOG_FILE, `[${timestamp()}] DEBUG ${source}: ${message}\n`);
+    appendFileSync(path, `[${timestamp()}] DEBUG ${source}: ${message}\n`);
   } catch {
     /* non-critical */
   }
@@ -41,10 +88,11 @@ export function logDebug(source: string, message: string): void {
 
 /** Log an error (always written, regardless of PAL_DEBUG) */
 export function logError(source: string, error: unknown): void {
-  rotateIfNeeded();
+  const path = logFile();
+  rotateIfNeeded(path);
   const msg = error instanceof Error ? `${error.message}\n${error.stack}` : String(error);
   try {
-    appendFileSync(LOG_FILE, `[${timestamp()}] ERROR ${source}: ${msg}\n`);
+    appendFileSync(path, `[${timestamp()}] ERROR ${source}: ${msg}\n`);
   } catch {
     /* non-critical */
   }

package/src/hooks/lib/notify.ts

@@ -28,6 +28,7 @@ function escapePowerShellSingle(s: string): string {
 }
 
 export async function notify(title: string, body: string): Promise<void> {
+  if (process.env.PAL_NOTIFICATIONS_DISABLED === "1") return;
   if (process.platform === "darwin") {
     const script = `display notification "${escapeAppleScript(body)}" with title "${escapeAppleScript(title)}"`;
     await spawnSilent("osascript", ["-e", script]);

package/src/hooks/lib/projects.ts

@@ -43,6 +43,58 @@ export interface ProjectProgress {
   changelog?: string;
 }
 
+// ── Legacy migration types ────────────────────────────────────────
+// Shared by `pal cli migrate` and `pal tool agent project --migrate` —
+// both convert the old progress-JSON format to current ProjectProgress.
+
+interface LegacyDecision {
+  ts: string;
+  decision: string;
+  rationale: string;
+}
+
+interface LegacyProject {
+  name: string;
+  path: string;
+  status: ProjectStatus;
+  created: string;
+  updated: string;
+  facts?: string[];
+  objectives?: string[];
+  next_steps?: string[];
+  blockers?: string[];
+  handoff?: string;
+  decisions?: LegacyDecision[];
+}
+
+/**
+ * Convert a parsed legacy progress JSON object into the current ProjectProgress
+ * shape. Returns null if required fields (name/path/status) are missing.
+ */
+export function legacyJsonToProgress(raw: unknown): ProjectProgress | null {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw as LegacyProject;
+  if (!r.name || !r.path || !r.status) return null;
+  const p: ProjectProgress = {
+    name: r.name,
+    path: r.path,
+    status: r.status,
+    created: r.created ?? new Date().toISOString(),
+    updated: r.updated ?? new Date().toISOString(),
+    ...(r.handoff ? { handoff: r.handoff } : {}),
+    ...(r.next_steps?.length ? { next: r.next_steps } : {}),
+    ...(r.blockers?.length ? { blockers: r.blockers } : {}),
+  };
+  if (r.facts?.length) p.context = r.facts.join("\n");
+  if (r.objectives?.length) p.goal = r.objectives.map((o) => `- ${o}`).join("\n");
+  if (r.decisions?.length) {
+    p.decisions = r.decisions
+      .map((d) => `- ${d.ts.slice(0, 10)}: ${d.decision} (${d.rationale})`)
+      .join("\n");
+  }
+  return p;
+}
+
 const PROJECT_STALE_DAYS_DEFAULT = 14;
 
 const PROJECT_MARKERS = [

package/src/hooks/lib/retrieval-index.ts

@@ -191,6 +191,7 @@ function spawnBackgroundRebuild(): void {
       detached: true,
       stdio: "ignore",
       env: process.env,
+      windowsHide: true,
     });
     child.unref();
   } catch (err) {

package/src/hooks/lib/security.ts

@@ -32,6 +32,11 @@ const HOOK_MANAGED_FILES = [
   "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",

package/src/hooks/lib/spawn-guard.ts

@@ -0,0 +1,68 @@
+/**
+ * Spawn-guard — prevents PAL inference recursion.
+ *
+ * When the inference dispatcher (see src/hooks/lib/inference.ts) spawns an
+ * agent CLI (claude --print, codex exec, copilot -p, cursor-agent -p) for
+ * one-shot subscription-billed inference, it sets PAL_SPAWNED_INFERENCE=1
+ * and increments PAL_INFERENCE_DEPTH. PAL's own hooks check these on entry
+ * and short-circuit so the spawned subprocess does not itself trigger another
+ * inference call → infinite recursion.
+ *
+ * PRIMARY DEFENSE: per-agent CLI flags that disable hook loading in the
+ * spawned subprocess. PAI's canonical pattern (PAI/TOOLS/Inference.ts):
+ *   --setting-sources ''    → no settings.json → no hooks load
+ *   --tools ''              → no tool calls → no PreToolUse triggers
+ *   --system-prompt <x>     → explicit prompt instead of loaded default
+ * The dispatcher in step 3 must mirror this per supported agent.
+ *
+ * SECONDARY DEFENSE (this file): an env-var sentinel that survives across
+ * spawn boundaries. Catches cases where (a) we get a CLI flag wrong, (b) an
+ * agent CLI does not expose clean equivalents to claude's flags, (c) the
+ * environment leaks unexpectedly. Belt and suspenders.
+ */
+
+export const SPAWN_GUARD_ENV = {
+  /** Set to "1" by the dispatcher before spawning. Checked by every PAL hook. */
+  SENTINEL: "PAL_SPAWNED_INFERENCE",
+  /** Stringified integer. Incremented by the dispatcher; absent = 0. */
+  DEPTH: "PAL_INFERENCE_DEPTH",
+  /** Hard cap. Dispatcher MUST refuse to spawn when current depth >= MAX_DEPTH. */
+  MAX_DEPTH: 1,
+} as const;
+
+/** True when the current process is a PAL-spawned inference subprocess. */
+export function isPalSpawnedInference(): boolean {
+  return process.env[SPAWN_GUARD_ENV.SENTINEL] === "1";
+}
+
+/** How many PAL inference spawns deep we are. 0 = top-level user session. */
+export function getInferenceDepth(): number {
+  const raw = process.env[SPAWN_GUARD_ENV.DEPTH];
+  if (!raw) return 0;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+/**
+ * Build the env a dispatcher applies before spawn. Returns a new object;
+ * `parentEnv` is never mutated. Sets the recursion sentinel, increments depth,
+ * and unsets CLAUDECODE so the child claude CLI does not trip its
+ * nested-session guard. CLAUDECODE: undefined is scoped to the child only —
+ * the parent process and OS env are untouched.
+ */
+export function buildSpawnGuardEnv(parentEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const nextDepth = getInferenceDepthFrom(parentEnv) + 1;
+  return {
+    ...parentEnv,
+    [SPAWN_GUARD_ENV.SENTINEL]: "1",
+    [SPAWN_GUARD_ENV.DEPTH]: String(nextDepth),
+    CLAUDECODE: undefined,
+  };
+}
+
+function getInferenceDepthFrom(env: NodeJS.ProcessEnv): number {
+  const raw = env[SPAWN_GUARD_ENV.DEPTH];
+  if (!raw) return 0;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}

package/src/hooks/lib/stop.ts

@@ -4,25 +4,23 @@
  */
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { readFile, unlink } from "node:fs/promises";
+import { mkdtemp, rename, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
 import { resolve } from "node:path";
-import { autoGraduate } from "../handlers/auto-graduate";
 import { autoBackup } from "../handlers/backup";
 import { writeContextDigests } from "../handlers/context-digests";
 import { notifyDesktop } from "../handlers/desktop-notify";
-import { captureFailure } from "../handlers/failure";
 import { persistLastExchange } from "../handlers/persist-last-exchange";
 import { projectTouch } from "../handlers/project-touch";
 import { checkReflectTrigger } from "../handlers/reflect-trigger";
 import { checkSelfModelTrigger } from "../handlers/self-model-trigger";
-import { captureSessionIntelligence } from "../handlers/session-intelligence";
 import { runSynthesis } from "../handlers/synthesis";
 import { resetTab } from "../handlers/tab";
 import { updateCounts } from "../handlers/update-counts";
 import { captureWorkSession } from "../handlers/work-session";
-import { inference } from "./inference";
+import { spawnDetachedInference } from "./detached-inference";
 import { logDebug, logError } from "./log";
-import { ensureDir, paths } from "./paths";
+import { assets, ensureDir, paths } from "./paths";
 import { extractContent, extractLastAssistant, parseMessages } from "./transcript";
 
 interface RunStopHandlersOptions {
@@ -46,20 +44,25 @@ export async function runStopHandlers(
   // Always persist last exchange — drives CompactRecover + "Pick Up Where You Left Off"
   if (options.sessionId) persistLastExchange(messages, options.sessionId);
 
-  // Run all handlers concurrently. Auto-graduate is idempotent (24h TTL +
-  // state-dedup + content-dedup) so it's safe to fire on every Stop.
+  // Detach inference-bearing handlers — claude --print cold-start can exceed
+  // any in-hook budget. These spawn detached bun subprocesses that run the
+  // inference and write results to disk; they don't block this hook.
+  // autoGraduate is idempotent (24h TTL + state-dedup + content-dedup), so
+  // concurrent or overlapping detached runs are safe.
+  await detachSessionIntelligence(transcript, options.sessionId);
+  await detachFailurePrinciple(transcript);
+  detachAutoGraduate();
+
+  // Run remaining (non-inference) handlers concurrently.
   // project-touch only fires when cwd resolves to an active registered project.
   const results = await Promise.allSettled([
     captureWorkSession(transcript, options.sessionId),
     resetTab(),
-    captureSessionIntelligence(transcript, options.sessionId),
-    checkPendingFailure(transcript),
     updateCounts(),
     autoBackup(),
     checkReflectTrigger(),
     checkSelfModelTrigger(),
     runSynthesis(),
-    autoGraduate(),
     projectTouch(options.lastAssistantMessage),
     notifyDesktop(options.sessionId),
     Promise.resolve(writeContextDigests()),
@@ -68,14 +71,11 @@ export async function runStopHandlers(
   const handlerNames = [
     "work-session",
     "tab",
-    "session-intelligence",
-    "pending-failure",
     "update-counts",
     "backup",
     "reflect-trigger",
     "self-model-trigger",
     "synthesis",
-    "auto-graduate",
     "project-touch",
     "desktop-notify",
     "context-digests",
@@ -151,76 +151,74 @@ function cacheLastResponse(
   }
 }
 
-async function checkPendingFailure(transcript: string): Promise<void> {
+/** Write transcript to a fresh tmp file and return the path. Child unlinks it. */
+async function writeTranscriptTmp(transcript: string): Promise<string> {
+  const dir = await mkdtemp(resolve(tmpdir(), "pal-transcript-"));
+  const file = resolve(dir, "transcript.txt");
+  await writeFile(file, transcript, "utf-8");
+  return file;
+}
+
+/** Spawn a detached child to run session-intelligence on a tmp copy of the transcript. */
+async function detachSessionIntelligence(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  try {
+    const transcriptPath = await writeTranscriptTmp(transcript);
+    const scriptPath = resolve(assets.hooks(), "handlers", "session-intelligence.ts");
+    spawnDetachedInference(
+      scriptPath,
+      ["--run", sessionId ?? "", transcriptPath],
+      "session-intelligence"
+    );
+  } catch (err) {
+    logError("detachSessionIntelligence", err);
+  }
+}
+
+/** Spawn a detached child to run the full autoGraduate cycle. */
+function detachAutoGraduate(): void {
+  try {
+    const scriptPath = resolve(assets.hooks(), "handlers", "auto-graduate.ts");
+    spawnDetachedInference(scriptPath, ["--run"], "auto-graduate");
+  } catch (err) {
+    logError("detachAutoGraduate", err);
+  }
+}
+
+/**
+ * If a pending-failure exists, rename it to a unique path (race-free claim),
+ * write the transcript to tmp, spawn the failure-principle handler detached.
+ */
+async function detachFailurePrinciple(transcript: string): Promise<void> {
   const pendingPath = resolve(paths.state(), "pending-failure.json");
   if (!existsSync(pendingPath)) return;
 
+  // Rename to claim the pending file atomically — prevents two Stop hooks
+  // racing on the same low rating (opencode notably fires session.idle AND
+  // session.diff concurrently, so runStopHandlers runs twice in parallel).
+  const claimedDir = await mkdtemp(resolve(tmpdir(), "pal-pending-"));
+  const claimedPath = resolve(claimedDir, "pending.json");
   try {
-    const pending = JSON.parse(await readFile(pendingPath, "utf-8")) as {
-      rating: number;
-      context: string;
-      detailedContext?: string;
-      principle?: string;
-      responsePreview?: string;
-      userPreview?: string;
-      cwd?: string;
-    };
-    await unlink(pendingPath);
-
-    // Extract principle from full transcript if not already present
-    let { principle, detailedContext } = pending;
-    if (!principle) {
-      try {
-        const msgs = parseMessages(transcript);
-        const recent = msgs
-          .slice(-10)
-          .map((m) => `${m.role.toUpperCase()}: ${extractContent(m).slice(0, 300)}`)
-          .join("\n\n");
-
-        const result = await inference({
-          system: `Analyze this failed AI interaction. The user rated it ${pending.rating}/10.
-
-Return JSON:
-{
-  "principle": "<one actionable rule the AI should follow, 10-20 words. Start with a verb: 'Verify...', 'Always...', 'Never...', 'Ask before...'>",
-  "detailed_context": "<what went wrong and why, 50-150 words>"
-}`,
-          user: `User feedback: ${pending.context}\n\nConversation:\n${recent}`,
-          maxTokens: 400,
-          timeout: 10000,
-          jsonSchema: {
-            type: "object" as const,
-            properties: {
-              principle: { type: "string" as const },
-              detailed_context: { type: "string" as const },
-            },
-            required: ["principle", "detailed_context"],
-            additionalProperties: false,
-          },
-        });
-
-        if (result.success && result.output) {
-          const parsed = JSON.parse(result.output) as {
-            principle?: string;
-            detailed_context?: string;
-          };
-          principle = parsed.principle || undefined;
-          detailedContext ??= parsed.detailed_context || undefined;
-        }
-      } catch {
-        /* graceful fallback — capture without principle */
-      }
-    }
+    await rename(pendingPath, claimedPath);
+  } catch (err) {
+    // ENOENT means another concurrent Stop hook already claimed it. That's
+    // expected and benign — the other process will handle the failure.
+    if ((err as NodeJS.ErrnoException)?.code === "ENOENT") return;
+    logError("detachFailurePrinciple", err);
+    return;
+  }
 
-    await captureFailure(
-      pending.rating,
-      pending.context,
-      transcript,
-      detailedContext,
-      principle,
-      pending.cwd
+  try {
+    const transcriptPath = await writeTranscriptTmp(transcript);
+    const scriptPath = resolve(assets.hooks(), "handlers", "failure-principle.ts");
+    spawnDetachedInference(
+      scriptPath,
+      ["--run", claimedPath, transcriptPath],
+      "failure-principle"
     );
-  } catch {
-    // Non-critical
+  } catch (err) {
+    logError("detachFailurePrinciple", err);
   }
 }

package/src/targets/opencode/plugin.ts

@@ -10,6 +10,13 @@ import type { Plugin, PluginInput } from "@opencode-ai/plugin";
 
 const PAL_DIR = process.env.PAL_DIR || resolve(import.meta.dir, "../../..");
 
+// Identify ourselves as opencode for the shared detector in hooks/lib/agent.ts.
+// Force-override (= not ??=) so an inherited PAL_AGENT from the parent shell
+// — common when launching opencode from a Claude Code terminal — doesn't make
+// the dispatcher route inference to the wrong agent's CLI. Mirrors how
+// .claude/settings.json template prefixes every hook command with PAL_AGENT=claude.
+process.env.PAL_AGENT = "opencode";
+
 // Dynamic imports from shared lib — resolved at runtime via PAL_DIR
 async function lib<T>(mod: string): Promise<T> {
   return await import(resolve(PAL_DIR, "src", "hooks", "lib", mod));
@@ -74,15 +81,20 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       .filter((m) => m.content.length > 0);
   }
 
+  const { isPalSpawnedInference } =
+    await lib<typeof import("../../hooks/lib/spawn-guard")>("spawn-guard.ts");
+
   return {
     // --- Per-message: Inject dynamic system reminder ---
     "experimental.chat.system.transform": async (_input, output) => {
+      if (isPalSpawnedInference()) return;
       const reminder = buildSystemReminder({ agent: "opencode" });
       if (reminder) output.system.push(reminder);
     },
 
     // --- Session events: start and stop handling ---
     event: async ({ event }) => {
+      if (isPalSpawnedInference()) return;
       logDebug("opencode:event", `Event: ${event.type}`);
 
       if (event.type === "session.created" || event.type === "session.updated") {
@@ -123,6 +135,7 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
 
     // --- Capture ratings + session naming from user messages (shared handlers) ---
     "chat.message": async (input, output) => {
+      if (isPalSpawnedInference()) return;
       const text = partsToText(output.parts ?? []);
       if (!text.trim()) return;
 

package/src/tools/agent/project.ts

@@ -29,6 +29,7 @@ import {
   defaultSlug,
   deleteProject,
   isStale,
+  legacyJsonToProgress,
   type ProjectProgress,
   type ProjectStatus,
   readAllProjects,
@@ -276,26 +277,6 @@ function cmdIsaInit(args: string[]): void {
 
 // ── migrate (from old JSON format) ───────────────────────────────
 
-interface LegacyDecision {
-  ts: string;
-  decision: string;
-  rationale: string;
-}
-
-interface LegacyProject {
-  name: string;
-  path: string;
-  status: ProjectStatus;
-  created: string;
-  updated: string;
-  facts?: string[];
-  objectives?: string[];
-  next_steps?: string[];
-  blockers?: string[];
-  handoff?: string;
-  decisions?: LegacyDecision[];
-}
-
 function cmdMigrate(): void {
   const progressDir = paths.progress();
   if (!existsSync(progressDir)) {
@@ -324,32 +305,13 @@ function cmdMigrate(): void {
     }
 
     try {
-      const raw = JSON.parse(readFileSync(filePath, "utf-8")) as LegacyProject;
-      if (!raw?.name || !raw?.path || !raw?.status) {
+      const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+      const p = legacyJsonToProgress(raw);
+      if (!p) {
         skipped++;
         results.push(`${slug}: skipped (malformed JSON)`);
         continue;
       }
-
-      const p: ProjectProgress = {
-        name: raw.name,
-        path: raw.path,
-        status: raw.status,
-        created: raw.created,
-        updated: raw.updated,
-        ...(raw.handoff ? { handoff: raw.handoff } : {}),
-        ...(raw.next_steps?.length ? { next: raw.next_steps } : {}),
-        ...(raw.blockers?.length ? { blockers: raw.blockers } : {}),
-      };
-
-      if (raw.facts?.length) p.context = raw.facts.join("\n");
-      if (raw.objectives?.length) p.goal = raw.objectives.map((o) => `- ${o}`).join("\n");
-      if (raw.decisions?.length) {
-        p.decisions = raw.decisions
-          .map((d) => `- ${d.ts.slice(0, 10)}: ${d.decision} (${d.rationale})`)
-          .join("\n");
-      }
-
       writeProject(p);
       migrated++;
       results.push(`${slug}: migrated`);

package/src/tools/self-model.ts

@@ -540,6 +540,7 @@ async function composeSelfModel(days: number): Promise<string> {
     model: SONNET_MODEL,
     maxTokens: 1500,
     timeout: 30000,
+    caller: "self-model",
   });
 
   if (result.usage) logTokenUsage("self-model", result.usage, SONNET_MODEL);