portable-agent-layer 0.85.11 → 0.85.13

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.11",
+  "version": "0.85.13",
   "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,11 +11,25 @@ interface PendingMigration {
   detail?: string;
 }
 
+const CLAUDE_LOGIN_EXPIRED = /Failed to authenticate/;
+
+function claudeLoginExpiredFinding(group: HookErrorGroup): Finding {
+  return failing(
+    `hook-errors.${group.source}`,
+    `Background calls to Claude cannot log in — ${group.count} failed in the last 24h: ${group.last}`,
+    {
+      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[]): 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);
     const times = group.count === 1 ? "once" : `${group.count} times`;
     return warning(
       `hook-errors.${group.source}`,

package/src/cli/doctor/state.ts

@@ -209,13 +209,43 @@ function bindingFindings(): Finding[] {
     : issues.map(bindingFinding);
 }
 
+function resolves(name: string, from: string): boolean {
+  try {
+    Bun.resolveSync(`${name}/package.json`, from);
+    return true;
+  } catch {
+    try {
+      Bun.resolveSync(name, from);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export function unresolvedDependencies(pkg: string): string[] {
+  try {
+    const { dependencies = {} } = JSON.parse(
+      readFileSync(resolve(pkg, "package.json"), "utf-8")
+    );
+    return Object.keys(dependencies).filter((name) => !resolves(name, pkg));
+  } catch {
+    return [];
+  }
+}
+
 function dependencyFinding(): Finding {
-  return existsSync(resolve(palPkg(), "node_modules"))
+  const missing = unresolvedDependencies(palPkg());
+  return missing.length === 0
     ? passed("dependencies", "Dependencies installed")
-    : failing("dependencies", "PAL's dependencies are not installed", {
-        say: "Install them",
-        command: "pal cli install",
-      });
+    : failing(
+        "dependencies",
+        `PAL's dependencies do not resolve: ${missing.join(", ")}`,
+        {
+          say: "Install them",
+          command: "pal cli install",
+        }
+      );
 }
 
 export function stateFindings(): Finding[] {

package/src/cli/migrate.ts

@@ -642,6 +642,77 @@ 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;
+  }
+}
+
+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 +720,7 @@ const MIGRATIONS: Migration[] = [
   v4PathsToBindings,
   v5AttributionKeys,
   v6HistorySlugs,
+  v7RetiredSettingsKeys,
 ];
 
 // ── Public API ────────────────────────────────────────────────────

package/src/hooks/lib/log.ts

@@ -108,16 +108,19 @@ function loggedAt(line: string): number {
   return match ? Date.parse(`${match[1]}T${match[2]}Z`) : 0;
 }
 
+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: string[]): 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: "" };
     group.count++;
-    group.last = error
-      .slice(source.length + 1)
-      .trim()
-      .slice(0, 120);
+    group.last = whatTheAgentSaid(error.slice(source.length + 1).trim()).slice(0, 120);
     groups.set(source, group);
   }
   return [...groups.values()].sort((a, b) => b.count - a.count);

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