portable-agent-layer 0.85.13 → 0.85.15

package/package.json

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

package/src/cli/doctor/environment.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
@@ -67,22 +68,47 @@ function playwrightPlatformOverride(host: BrowserHost): string {
   return `PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-${host.arch === "arm64" ? "arm64" : "x64"} `;
 }
 
+function chromiumInstallCommand(host: BrowserHost): string {
+  const pinned = host.playwright ? `playwright@${host.playwright.version}` : "playwright";
+  return `${playwrightPlatformOverride(host)}bun x ${pinned} install chromium`;
+}
+
 export function playwrightFinding(host: BrowserHost): Finding {
   if (hasChromium(host)) return passed("playwright", "Playwright Chromium installed");
-  const pinned = host.playwright ? `playwright@${host.playwright.version}` : "playwright";
-  const override = playwrightPlatformOverride(host);
   return warning(
     "playwright.missing",
     "Playwright's Chromium is not installed — create-pdf, consulting-report and screenshots fail",
     {
-      say: override
+      say: playwrightPlatformOverride(host)
         ? "Install it as Ubuntu 24.04, which Playwright supports"
         : "Install it",
-      command: `${override}bun x ${pinned} install chromium`,
+      command: chromiumInstallCommand(host),
     }
   );
 }
 
+function thisBrowserHost(): BrowserHost {
+  return {
+    browsersPath: playwrightBrowsersPath(),
+    playwright: installedPlaywright(),
+    platform: process.platform,
+    arch: process.arch,
+    osRelease: readOsRelease(),
+  };
+}
+
+function runInShell(command: string): boolean {
+  return spawnSync(command, { cwd: palPkg(), shell: true, stdio: "ignore" }).status === 0;
+}
+
+/** A failure is left to the doctor's report that follows, which names the fix. */
+export function installChromium(
+  host: BrowserHost = thisBrowserHost(),
+  run: (command: string) => boolean = runInShell
+): void {
+  if (!hasChromium(host)) run(chromiumInstallCommand(host));
+}
+
 interface PalInstall {
   pal: string | null;
   pkg: string;
@@ -136,13 +162,7 @@ export function environmentFindings(rtk: ToolCheck): Finding[] {
       pkg: palPkg(),
       repoMode: isRepoMode(),
     }),
-    playwrightFinding({
-      browsersPath: playwrightBrowsersPath(),
-      playwright: installedPlaywright(),
-      platform: process.platform,
-      arch: process.arch,
-      osRelease: readOsRelease(),
-    }),
+    playwrightFinding(thisBrowserHost()),
     rtkFinding(rtk),
     ...versionControlFindings(),
   ];

package/src/cli/doctor/health.ts

@@ -11,29 +11,49 @@ interface PendingMigration {
   detail?: string;
 }
 
+interface ErrorContext {
+  now: number;
+  env: Record<string, string | undefined>;
+}
+
 const CLAUDE_LOGIN_EXPIRED = /Failed to authenticate/;
+const MINUTE_MS = 60_000;
 
-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",
+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[]): Finding[] {
+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);
+    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/index.ts

@@ -50,10 +50,10 @@ import { inference, previewInferenceRoute } from "../hooks/lib/inference";
 import { logDebug } from "../hooks/lib/log";
 import { ensureRegistered, writeRegistryEntry } from "../hooks/lib/machine";
 import { palHome, palPkg, paths, platform, toPath } from "../hooks/lib/paths";
-import { telosStatus } from "../hooks/lib/telos-topics";
-import { log } from "../targets/lib";
+import { log, narrateSteps } from "../targets/lib";
 import { builtinToolVerbs, runBuiltinTool } from "./builtin-tools";
 import { type DoctorResult, detectAgents } from "./doctor/agents";
+import { installChromium } from "./doctor/environment";
 import { runDoctor } from "./doctor/run";
 import { findSessionAgent, NO_SESSION_AGENT_MESSAGE } from "./session-agent";
 
@@ -155,7 +155,7 @@ async function runCli(command: string | undefined, args: string[]) {
       break;
     case "install":
       banner();
-      await install(resolveTargets(args));
+      process.exit(await install(resolveTargets(args), args));
       break;
     case "uninstall":
       await uninstall(args);
@@ -265,24 +265,10 @@ function banner() {
   console.log("");
   console.log("  ╔═══════════════════════════════════╗");
   console.log("  ║  PAL — Portable Agent Layer       ║");
-  console.log("  ║  Non-destructive · Modular        ║");
   console.log("  ╚═══════════════════════════════════╝");
   console.log("");
 }
 
-/**
- * Install asks for identity and stops. TELOS is a conversation, not a form: a
- * user who has just installed a tool cannot yet say what they want from it, and
- * answers given under that pressure are worse than none.
- */
-function pointAtOnboarding(): void {
-  const unanswered = telosStatus().filter((topic) => topic.priority && !topic.answered);
-  if (unanswered.length === 0) return;
-  log.info(
-    `PAL knows nothing about you yet (${unanswered.length} topics open). When you have half an hour, ask your agent to onboard you.`
-  );
-}
-
 function showHelp() {
   console.log(`
   Usage:
@@ -290,8 +276,9 @@ function showHelp() {
     pal cli <command> [options]             Admin commands
 
   Admin commands:
-    pal cli init [--claude] [--opencode] [--cursor] [--codex]    Scaffold and install (default: all)
-    pal cli install [--claude] [--opencode] [--cursor] [--codex] Register hooks for targets
+    pal cli init [--claude] [--opencode] [--cursor] [--codex]    Scaffold and install (default: all), then run the doctor
+    pal cli install [--claude] [--opencode] [--cursor] [--codex] Register hooks for targets, then run the doctor
+                                            Add --verbose to either for the step-by-step log
     pal cli uninstall [--claude] [--opencode] [--cursor] [--codex] Remove hooks for targets
     pal cli update                          Update PAL (git pull or npm update)
     pal cli export [path] [--dry-run]       Export state to zip
@@ -486,12 +473,10 @@ async function init(args: string[]) {
   const { scaffoldTelos } = await import("../targets/lib");
 
   banner();
+  narrateSteps(args.includes("--verbose"));
 
   const health = detectAgents();
-  runDoctor([], health);
-  if (!health.hasAgent) {
-    process.exit(1);
-  }
+  if (!health.hasAgent) process.exit(runDoctor([], health));
 
   const home = palHome();
   log.info(`Creating PAL home at ${home}`);
@@ -506,7 +491,7 @@ async function init(args: string[]) {
 
   // Auto-detect available targets
   const targets = resolveTargets(args, health);
-  await install(targets);
+  process.exit(await install(targets, args));
 }
 
 /**
@@ -522,25 +507,25 @@ function runQuietly(cmd: string, args: string[], cwd: string): number | null {
   return r.status;
 }
 
-async function install(targets: Targets) {
-  // Ensure dependencies are installed
+function targetInstallers(): [keyof Targets, string, () => Promise<unknown>][] {
+  return [
+    ["claude", "Claude Code", () => import("../targets/claude/install")],
+    ["opencode", "opencode", () => import("../targets/opencode/install")],
+    ["cursor", "Cursor", () => import("../targets/cursor/install")],
+    ["copilot", "Copilot", () => import("../targets/copilot/install")],
+    ["codex", "Codex", () => import("../targets/codex/install")],
+  ];
+}
+
+async function install(targets: Targets, args: string[]): Promise<number> {
+  narrateSteps(args.includes("--verbose"));
   const pkg = palPkg();
   if (runQuietly("bun", ["install", "--frozen-lockfile"], pkg) !== 0) {
     log.warn("bun install failed — continuing anyway, but hooks may not work");
   }
 
-  // Fetch the Chromium build Playwright uses for PDF rendering (create-pdf skill).
-  // Idempotent — skipped if already cached. Skipped entirely under PAL_SKIP_BROWSER_INSTALL=1
-  // (used by tests to avoid a ~150MB download on every run).
   // Uses `bun x` (not `bunx`) for Windows compatibility — bunx resolves unreliably under cmd.exe.
-  if (process.env.PAL_SKIP_BROWSER_INSTALL !== "1") {
-    const pw = runQuietly("bun", ["x", "playwright", "install", "chromium"], pkg);
-    if (pw !== 0) {
-      log.warn(
-        `playwright install chromium failed (exit ${pw}) — create-pdf and consulting-report skills won't work. Retry manually: bun x playwright install chromium`
-      );
-    }
-  }
+  if (process.env.PAL_SKIP_BROWSER_INSTALL !== "1") installChromium();
 
   // Scaffold TELOS + PAL settings, then prompt for missing identity
   const { scaffoldTelos, scaffoldPalSettings, copyPalDocs, generateSkillIndex } =
@@ -553,7 +538,6 @@ async function install(targets: Targets) {
   await promptIdentity();
   await promptAttribution();
   await promptAutoUpdate();
-  pointAtOnboarding();
 
   // Registers the label loadActor derives, so it travels on the next export.
   const { ensureActorRegistered } = await import("../hooks/lib/actor");
@@ -566,34 +550,10 @@ async function install(targets: Targets) {
   const palDocsCount = copyPalDocs();
   regenerateIfNeeded();
 
-  if (targets.claude) {
-    console.log("━━━ Claude Code ━━━");
-    await import("../targets/claude/install");
-    console.log("");
-  }
-
-  if (targets.opencode) {
-    console.log("━━━ opencode ━━━");
-    await import("../targets/opencode/install");
-    console.log("");
-  }
-
-  if (targets.cursor) {
-    console.log("━━━ Cursor ━━━");
-    await import("../targets/cursor/install");
-    console.log("");
-  }
-
-  if (targets.copilot) {
-    console.log("━━━ Copilot ━━━");
-    await import("../targets/copilot/install");
-    console.log("");
-  }
-
-  if (targets.codex) {
-    console.log("━━━ Codex ━━━");
-    await import("../targets/codex/install");
-    console.log("");
+  for (const [target, label, installTarget] of targetInstallers()) {
+    if (!targets[target]) continue;
+    log.heading(label);
+    await installTarget();
   }
 
   // The rest of the shared work reads what the installers just wrote: the index
@@ -608,7 +568,8 @@ async function install(targets: Targets) {
 
   await refreshControlRoom();
 
-  log.success("Done. Existing config was preserved — only new entries were added.");
+  if (args.includes("--verbose")) console.log("");
+  return runDoctor(args);
 }
 
 /**
@@ -912,7 +873,7 @@ async function update() {
   clearUpdateCache();
 
   log.info("Reinstalling...");
-  await install(resolveTargets([]));
+  process.exit(await install(resolveTargets([]), []));
 }
 
 function cliDebug(args: string[]) {

package/src/cli/migrate.ts

@@ -671,7 +671,9 @@ function readSettingsObject(): Record<string, Record<string, unknown>> | null {
   }
 }
 
-function retiredKeysIn(settings: Record<string, Record<string, unknown>>): string[] {
+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 [];

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;
@@ -114,13 +120,14 @@ function whatTheAgentSaid(message: string): string {
   return output[1].trim() || output[2].trim() || message;
 }
 
-function groupBySource(errors: string[]): HookErrorGroup[] {
+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 = whatTheAgentSaid(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);
@@ -131,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

@@ -27,9 +27,21 @@ function runningUnderTest(): boolean {
   return process.env.PAL_TEST_SANDBOX === "1";
 }
 
+let narrating = true;
+
+/** Install's step log is for --verbose; the doctor report that follows carries the result. */
+export function narrateSteps(on: boolean): void {
+  narrating = on;
+}
+
+function narrate(line: string): void {
+  if (narrating) console.log(line);
+}
+
 export const log = {
-  info: (msg: string) => console.log(`\x1b[34m[pal]\x1b[0m ${msg}`),
-  success: (msg: string) => console.log(`\x1b[32m[pal]\x1b[0m ${msg}`),
+  info: (msg: string) => narrate(`\x1b[34m[pal]\x1b[0m ${msg}`),
+  success: (msg: string) => narrate(`\x1b[32m[pal]\x1b[0m ${msg}`),
+  heading: (label: string) => narrate(`\n━━━ ${label} ━━━`),
   warn: (msg: string) => console.log(`\x1b[33m[pal]\x1b[0m ${msg}`),
   error: (msg: string) => console.error(`\x1b[31m[pal]\x1b[0m ${msg}`),
 
@@ -42,7 +54,7 @@ export const log = {
    */
   detail: (msg: string) => {
     if (runningUnderTest()) return;
-    console.log(`\x1b[34m[pal]\x1b[0m ${msg}`);
+    narrate(`\x1b[34m[pal]\x1b[0m ${msg}`);
   },
 };