portable-agent-layer 0.85.12 → 0.85.14

package/README.md

@@ -51,10 +51,10 @@ bun install
 bun run install:all
 ```
 
-In repo mode, add an alias to your shell profile:
+Then put `pal` on your PATH from the checkout. An alias is not enough: agents run skills in non-interactive shells, which never load it.
 
 ```bash
-alias pal="bun run ~/path/to/portable-agent-layer/src/cli/index.ts"
+bun link
 ```
 
 ---

package/package.json

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

package/src/cli/doctor/environment.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
+import { isRepoMode } from "../../hooks/handlers/update-check";
 import { palPkg } from "../../hooks/lib/paths";
 import { findBinaryOnPath } from "../../hooks/lib/which";
 import type { ToolCheck } from "./agents";
@@ -82,14 +83,29 @@ export function playwrightFinding(host: BrowserHost): Finding {
   );
 }
 
-function palOnPathFinding(): Finding {
-  const pal = findBinaryOnPath("pal");
-  return pal
-    ? passed("pal.path", `pal on PATH — ${pal}`)
-    : failing("pal.path", "pal is not on PATH — skills that run 'pal cli …' fail", {
-        say: "Install PAL globally",
-        command: "bun add -g portable-agent-layer",
-      });
+interface PalInstall {
+  pal: string | null;
+  pkg: string;
+  repoMode: boolean;
+}
+
+function putPalOnPath(install: PalInstall): Fix {
+  return install.repoMode
+    ? {
+        say: "Link the checkout — a shell alias is invisible to agents",
+        command: `cd ${install.pkg} && bun link`,
+      }
+    : { say: "Install PAL globally", command: "bun add -g portable-agent-layer" };
+}
+
+export function palOnPathFinding(install: PalInstall): Finding {
+  return install.pal
+    ? passed("pal.path", `pal on PATH — ${install.pal}`)
+    : failing(
+        "pal.path",
+        "pal is not on PATH — skills that run 'pal cli …' fail",
+        putPalOnPath(install)
+      );
 }
 
 function rtkInstall(): Fix {
@@ -115,7 +131,11 @@ function rtkFinding(rtk: ToolCheck): Finding {
 export function environmentFindings(rtk: ToolCheck): Finding[] {
   return [
     passed("bun", `Bun ${Bun.version}`),
-    palOnPathFinding(),
+    palOnPathFinding({
+      pal: findBinaryOnPath("pal"),
+      pkg: palPkg(),
+      repoMode: isRepoMode(),
+    }),
     playwrightFinding({
       browsersPath: playwrightBrowsersPath(),
       playwright: installedPlaywright(),

package/src/cli/doctor/health.ts

@@ -3,7 +3,7 @@ import { cachedStatus, type UpdateCache } from "../../hooks/handlers/update-chec
 import { type HookErrorGroup, recentHookErrors } from "../../hooks/lib/log";
 import { palHome } from "../../hooks/lib/paths";
 import { checkPendingMigrations } from "../migrate";
-import { type Finding, passed, warning } from "./finding";
+import { type Finding, failing, passed, warning } from "./finding";
 
 interface PendingMigration {
   id: string;
@@ -11,15 +11,49 @@ interface PendingMigration {
   detail?: string;
 }
 
-export function hookErrorFindings(groups: HookErrorGroup[]): Finding[] {
+interface ErrorContext {
+  now: number;
+  env: Record<string, string | undefined>;
+}
+
+const CLAUDE_LOGIN_EXPIRED = /Failed to authenticate/;
+const MINUTE_MS = 60_000;
+
+function ago(at: number, now: number): string {
+  const minutes = Math.max(0, Math.round((now - at) / MINUTE_MS));
+  return minutes < 60 ? `${minutes}m ago` : `${Math.floor(minutes / 60)}h ago`;
+}
+
+function claudeLoginExpiredFinding(
+  group: HookErrorGroup,
+  context: ErrorContext
+): Finding {
+  const title = `Background calls to Claude could not log in — ${group.count} failed in the last 24h, last ${ago(group.lastAt, context.now)}: ${group.last}`;
+  if (context.env.CLAUDE_CODE_OAUTH_TOKEN)
+    return warning(`hook-errors.${group.source}`, title, {
+      say: "CLAUDE_CODE_OAUTH_TOKEN is set — if these failures predate it, they clear 24h after the last one; if not, the token is invalid, so create a new one",
+      command: "claude setup-token",
+    });
+  return failing(`hook-errors.${group.source}`, title, {
+    say: "Create a year-long token, then export it as CLAUDE_CODE_OAUTH_TOKEN in your shell profile",
+    command: "claude setup-token",
+  });
+}
+
+export function hookErrorFindings(
+  groups: HookErrorGroup[],
+  context: ErrorContext = { now: Date.now(), env: process.env }
+): Finding[] {
   if (groups.length === 0)
     return [passed("hook-errors", "No hook errors in the last 24h")];
   const log = resolve(palHome(), "debug", "debug.log");
   return groups.map((group) => {
+    if (CLAUDE_LOGIN_EXPIRED.test(group.last))
+      return claudeLoginExpiredFinding(group, context);
     const times = group.count === 1 ? "once" : `${group.count} times`;
     return warning(
       `hook-errors.${group.source}`,
-      `${group.source} failed ${times} in the last 24h — last: ${group.last}`,
+      `${group.source} failed ${times} in the last 24h, last ${ago(group.lastAt, context.now)}: ${group.last}`,
       { say: `Full trace in ${log}` }
     );
   });

package/src/cli/doctor/state.ts

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { palHome, palPkg } from "../../hooks/lib/paths";
 import { auditBindings, type BindingIssue } from "../../hooks/lib/projects";
 import { telosStatus } from "../../hooks/lib/telos-topics";
+import { retiredKeysIn } from "../migrate";
 import { type Finding, failing, optional, passed, warning } from "./finding";
 
 interface SchemaNode {
@@ -142,7 +143,12 @@ function settingsFindings(): Finding[] {
       }),
     ];
   const schema = readSettingsSchema();
-  const unknown = schema ? unknownSettingsKeys(settings, schema) : [];
+  const leftToMigration = new Set(
+    retiredKeysIn(settings as Record<string, Record<string, unknown>>)
+  );
+  const unknown = schema
+    ? unknownSettingsKeys(settings, schema).filter((k) => !leftToMigration.has(k.path))
+    : [];
   return [identityFinding(settings), unknownKeysFinding(unknown)];
 }
 

package/src/cli/migrate.ts

@@ -642,6 +642,79 @@ const v6HistorySlugs: Migration = {
   },
 };
 
+// ── v7-retired-settings-keys: keys older settings templates wrote ──
+
+const RETIRED_SETTINGS_KEYS: Record<string, string[]> = {
+  loadAtStartup: ["_docs"],
+  steering: ["_docs"],
+  dynamicContext: [
+    "_docs",
+    "learningDigest",
+    "projectHistory",
+    "sessionIntelligence",
+    "synthesis",
+    "signalTrends",
+    "activeWork",
+  ],
+};
+
+function settingsFile(): string {
+  return resolve(paths.memory(), "pal-settings.json");
+}
+
+function readSettingsObject(): Record<string, Record<string, unknown>> | null {
+  try {
+    const settings = JSON.parse(readFileSync(settingsFile(), "utf-8"));
+    return typeof settings === "object" && settings !== null ? settings : null;
+  } catch {
+    return null;
+  }
+}
+
+export function retiredKeysIn(
+  settings: Record<string, Record<string, unknown>>
+): string[] {
+  return Object.entries(RETIRED_SETTINGS_KEYS).flatMap(([section, keys]) => {
+    const value = settings[section];
+    if (typeof value !== "object" || value === null) return [];
+    return keys.filter((key) => key in value).map((key) => `${section}.${key}`);
+  });
+}
+
+const v7RetiredSettingsKeys: Migration = {
+  id: "v7-retired-settings-keys",
+  description: "Remove settings older templates wrote that PAL no longer reads",
+
+  check() {
+    const settings = readSettingsObject();
+    const retired = settings ? retiredKeysIn(settings) : [];
+    return {
+      pending: retired.length > 0,
+      detail: retired.length > 0 ? retired.join(", ") : undefined,
+    };
+  },
+
+  run(dryRun = false): MigrationResult {
+    const settings = readSettingsObject();
+    const retired = settings ? retiredKeysIn(settings) : [];
+    if (!settings || retired.length === 0)
+      return { migrated: 0, skipped: 0, results: [] };
+    if (!dryRun) {
+      for (const path of retired) {
+        const [section, key] = path.split(".");
+        delete settings[section][key];
+      }
+      writeFileSync(settingsFile(), `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+    }
+    const verb = dryRun ? "would remove" : "removed";
+    return {
+      migrated: retired.length,
+      skipped: 0,
+      results: [`pal-settings.json: ${verb} ${retired.join(", ")}`],
+    };
+  },
+};
+
 const MIGRATIONS: Migration[] = [
   v1Projects,
   v2ThreadsToIsc,
@@ -649,6 +722,7 @@ const MIGRATIONS: Migration[] = [
   v4PathsToBindings,
   v5AttributionKeys,
   v6HistorySlugs,
+  v7RetiredSettingsKeys,
 ];
 
 // ── Public API ────────────────────────────────────────────────────

package/src/hooks/lib/log.ts

@@ -83,6 +83,12 @@ export interface HookErrorGroup {
   source: string;
   count: number;
   last: string;
+  lastAt: number;
+}
+
+interface LoggedError {
+  at: number;
+  message: string;
 }
 
 const DAY_MS = 24 * 60 * 60 * 1000;
@@ -108,16 +114,20 @@ function loggedAt(line: string): number {
   return match ? Date.parse(`${match[1]}T${match[2]}Z`) : 0;
 }
 
-function groupBySource(errors: string[]): HookErrorGroup[] {
+function whatTheAgentSaid(message: string): string {
+  const output = / stderr\(\d+\)=(.*?) stdout\(\d+\)=(.*)$/.exec(message);
+  if (!output) return message;
+  return output[1].trim() || output[2].trim() || message;
+}
+
+function groupBySource(errors: LoggedError[]): HookErrorGroup[] {
   const groups = new Map<string, HookErrorGroup>();
-  for (const error of errors) {
-    const source = /^([^:]+):/.exec(error)?.[1] ?? "unknown";
-    const group = groups.get(source) ?? { source, count: 0, last: "" };
+  for (const { at, message } of errors) {
+    const source = /^([^:]+):/.exec(message)?.[1] ?? "unknown";
+    const group = groups.get(source) ?? { source, count: 0, last: "", lastAt: 0 };
     group.count++;
-    group.last = error
-      .slice(source.length + 1)
-      .trim()
-      .slice(0, 120);
+    group.last = whatTheAgentSaid(message.slice(source.length + 1).trim()).slice(0, 120);
+    group.lastAt = at;
     groups.set(source, group);
   }
   return [...groups.values()].sort((a, b) => b.count - a.count);
@@ -128,7 +138,10 @@ export function recentHookErrors(now: number = Date.now()): HookErrorGroup[] {
     const recent = readAllLogs()
       .split("\n")
       .filter((line) => line.includes("] ERROR ") && loggedAt(line) > now - DAY_MS)
-      .map((line) => line.replace(/^\[.*?\] ERROR /, ""));
+      .map((line) => ({
+        at: loggedAt(line),
+        message: line.replace(/^\[.*?\] ERROR /, ""),
+      }));
     return groupBySource(recent);
   } catch {
     return [];

package/src/targets/lib.ts

@@ -17,7 +17,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, resolve, sep } from "node:path";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { assets, palHome, platform } from "../hooks/lib/paths";
 import { declaredTriggers } from "../hooks/lib/skill-triggers";
 
@@ -186,7 +186,7 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
     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));
+        return !cmd || !isOutdatedPalHook(cmd, palCanonical);
       });
       if (result.hooks[event].length === 0) delete result.hooks[event];
     }
@@ -390,7 +390,7 @@ export function mergeCursorHooks(
     // 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) => !palCanonical.has(canonicalPalCmd(e.command))
+        (e) => !isOutdatedPalHook(e.command, palCanonical)
       );
       if (result.hooks[event].length === 0) delete result.hooks[event];
     }
@@ -467,6 +467,15 @@ function canonicalPalCmd(cmd: string): string {
   return withoutEnv;
 }
 
+function runsRemovedPalHook(cmd: string): boolean {
+  const script = /bun\s+run\s+(\S+\/src\/hooks\/\S+\.ts)/.exec(cmd)?.[1];
+  return script !== undefined && isAbsolute(script) && !existsSync(script);
+}
+
+function isOutdatedPalHook(cmd: string, palCanonical: Set<string>): boolean {
+  return palCanonical.has(canonicalPalCmd(cmd)) || runsRemovedPalHook(cmd);
+}
+
 /**
  * True for path-scoped Grep()/Glob() allow rules, which Claude Code cannot honor —
  * it resolves Grep/Glob permission through Read(...) rules, so these never match and
@@ -507,11 +516,11 @@ function stripPalHooks(
     hooks[event] = (hooks[event] ?? [])
       .map((g) => {
         const flat = g as unknown as CodexHookCommand;
-        if (!g.hooks && flat.command && palCanonical.has(canonicalPalCmd(flat.command))) {
+        if (!g.hooks && flat.command && isOutdatedPalHook(flat.command, palCanonical)) {
           return null;
         }
         const filtered = (g.hooks ?? []).filter(
-          (h) => !palCanonical.has(canonicalPalCmd(h.command))
+          (h) => !isOutdatedPalHook(h.command, palCanonical)
         );
         return filtered.length > 0 ? { ...g, hooks: filtered } : null;
       })