portable-agent-layer 0.76.1 → 0.77.0

package/README.md

@@ -77,7 +77,7 @@ pal cli status        # check your setup
 | `pal cli init` | Scaffold PAL home directory and install hooks |
 | `pal cli install` | Register hooks/skills for targets |
 | `pal cli uninstall` | Remove hooks/skills for targets |
-| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks |
+| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this daily on its own; the switch lives in the control room under Settings → Updates. On a repo install a daily run waits while the clone has uncommitted changes |
 | `pal cli export` | Export user state (telos, memory) to a zip |
 | `pal cli import` | Import user state from a zip |
 | `pal cli status` | Show current PAL configuration |

package/assets/skills/consulting-report/tools/generate-pdf.ts

@@ -28,9 +28,9 @@ interface ReportMeta {
   reportTitle: string;
   classification: string;
   consultancyName: string;
-  /** Public path to consultancy logo (e.g. "/logos/konvert7.svg"). Used in the PDF footer. */
+  /** Public path to consultancy logo (e.g. "/logos/consultancy.svg"). Used in the PDF footer. */
   consultancyLogoSrc?: string;
-  /** Public path to client logo (e.g. "/logos/transcend.svg"). Used in the PDF header. */
+  /** Public path to client logo (e.g. "/logos/client.svg"). Used in the PDF header. */
   clientLogoSrc?: string;
 }
 

package/package.json

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

package/src/cli/index.ts

@@ -1245,10 +1245,12 @@ async function install(targets: Targets) {
     await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");
   const { promptAttribution } = await import("./setup-attribution");
+  const { promptAutoUpdate } = await import("./setup-auto-update");
   scaffoldTelos();
   scaffoldPalSettings();
   await promptIdentity();
   await promptAttribution();
+  await promptAutoUpdate();
   pointAtOnboarding();
 
   // Registers the label loadActor derives, so it travels on the next export.

package/src/cli/setup-auto-update.ts

@@ -0,0 +1,45 @@
+/**
+ * Daily unattended updates — one-time opt-in prompt.
+ *
+ * Asked once during `pal install`, the same seam git attribution uses, so a new
+ * user sees it at init and an existing one on their next update. The non-TTY
+ * guard is load-bearing twice over: it keeps CI silent, and it keeps the
+ * reinstall at the end of an unattended update from waiting on an answer nobody
+ * is there to give.
+ */
+
+import * as clack from "@clack/prompts";
+import { isRepoMode } from "../hooks/handlers/update-check";
+import { raw as readSettings, write as writeSettings } from "../hooks/lib/settings";
+
+/** Only a git clone can be mid-change; a global package install has no such state. */
+function whatItDoes(): string {
+  const daily = "Once a day, at session start, PAL updates itself in the background.";
+  return isRepoMode()
+    ? `${daily}\nIt waits while this clone has uncommitted changes.`
+    : daily;
+}
+
+export async function promptAutoUpdate(): Promise<void> {
+  if (!process.stdin.isTTY) return;
+
+  const settings = { ...readSettings() };
+  if (settings.autoUpdate?.decided) return;
+
+  clack.intro("Automatic updates");
+  clack.note(whatItDoes(), "Keep PAL up to date on its own?");
+
+  const enabled = await clack.confirm({
+    message: "Turn on daily automatic updates?",
+    initialValue: false,
+  });
+  if (clack.isCancel(enabled)) {
+    clack.cancel("Skipped — will ask again next time");
+    return;
+  }
+
+  settings.autoUpdate = { enabled: enabled === true, decided: true };
+  writeSettings(settings);
+  const state = enabled ? "Daily updates on" : "Daily updates off";
+  clack.outro(`${state} ✓  ·  change later: control room → Settings → Updates`);
+}

package/src/hooks/AutoUpdate.ts

@@ -0,0 +1,16 @@
+/**
+ * Spawned, never awaited — runs the daily self-update in a process of its own.
+ *
+ * LoadContext decides whether today's update is due; the control room's button
+ * starts this directly. Either way the work happens here so nothing waits on a
+ * git pull and a reinstall.
+ */
+
+import { runAutoUpdate } from "./lib/auto-update";
+import { logError } from "./lib/log";
+
+try {
+  runAutoUpdate();
+} catch (err) {
+  logError("AutoUpdate", err);
+}

package/src/hooks/LoadContext.ts

@@ -11,6 +11,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { getActiveAgent } from "./lib/agent";
+import { shouldAutoUpdate, spawnAutoUpdate } from "./lib/auto-update";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
 import { type AgentTarget, buildSystemReminder } from "./lib/context";
 import { logContextSnapshot, logDebug, logError } from "./lib/log";
@@ -38,6 +39,12 @@ try {
   logError("LoadContext:regenerate", err);
 }
 
+try {
+  if (shouldAutoUpdate()) spawnAutoUpdate();
+} catch (err) {
+  logError("LoadContext:auto-update", err);
+}
+
 try {
   const active = getActiveAgent();
   // The reminder is built for one of three targets; every other agent reads the

package/src/hooks/handlers/agenda.ts

@@ -343,7 +343,7 @@ async function writeMoves(sessionId?: string): Promise<boolean> {
       "You write the first three lines a person reads in the morning.",
       "You are given their goals and a ranked list of their projects and goals with the reason each was ranked.",
       "Write exactly three moves, most consequential first.",
-      "A move is a sentence naming an action, not a project name: 'Send ACE the mapping one-pager' beats 'work on ontology'.",
+      "A move is a sentence naming an action, not a project name: 'Send the supplier the revised quote' beats 'work on billing'.",
       "Prefer what is blocked on the person themselves, then what serves a goal, then what is merely urgent.",
       "Name the project each move belongs to, copying its slug exactly from the list you were given. A move that belongs to no project takes an empty string.",
       "Never invent a fact that is not in what you were given.",

package/src/hooks/handlers/update-check.ts

@@ -12,7 +12,7 @@ import { resolve } from "node:path";
 import { logDebug } from "../lib/log";
 import { ensureDir, palPkg, paths } from "../lib/paths";
 
-interface UpdateCache {
+export interface UpdateCache {
   checkedAt: string;
   available: boolean;
   current: string;
@@ -26,18 +26,24 @@ function cachePath(): string {
   return resolve(ensureDir(paths.state()), "update-available.json");
 }
 
-function readCache(): UpdateCache | null {
+/** The last check's result whatever its age — the notice and the page read this, not the TTL. */
+export function cachedStatus(): UpdateCache | null {
   try {
     const fp = cachePath();
     if (!existsSync(fp)) return null;
-    const cache = JSON.parse(readFileSync(fp, "utf-8")) as UpdateCache;
-    if (Date.now() - new Date(cache.checkedAt).getTime() < CACHE_TTL_MS) return cache;
-    return null; // expired
+    return JSON.parse(readFileSync(fp, "utf-8")) as UpdateCache;
   } catch {
     return null;
   }
 }
 
+function readCache(): UpdateCache | null {
+  const cache = cachedStatus();
+  if (!cache) return null;
+  const fresh = Date.now() - new Date(cache.checkedAt).getTime() < CACHE_TTL_MS;
+  return fresh ? cache : null;
+}
+
 function writeCache(cache: UpdateCache): void {
   try {
     writeFileSync(cachePath(), JSON.stringify(cache, null, 2), "utf-8");
@@ -50,7 +56,7 @@ export function isRepoMode(): boolean {
   return existsSync(resolve(palPkg(), ".git"));
 }
 
-function getInstalledVersion(): string {
+export function getInstalledVersion(): string {
   try {
     const pkg = JSON.parse(readFileSync(resolve(palPkg(), "package.json"), "utf-8"));
     return pkg.version || "0.0.0";
@@ -193,14 +199,7 @@ export function clearUpdateCache(): void {
 
 /** Read cached update status for greeting display. Returns null if no update. */
 export function getUpdateNotice(): string | null {
-  try {
-    const fp = cachePath();
-    if (!existsSync(fp)) return null;
-    const cache = JSON.parse(readFileSync(fp, "utf-8")) as UpdateCache;
-    if (!cache.available) return null;
-
-    return `📦 Update available: ${cache.current} → ${cache.latest} (pal cli update)`;
-  } catch {
-    return null;
-  }
+  const cache = cachedStatus();
+  if (!cache?.available) return null;
+  return `📦 Update available: ${cache.current} → ${cache.latest} (pal cli update)`;
 }

package/src/hooks/lib/auto-update.ts

@@ -0,0 +1,184 @@
+/**
+ * The daily self-update: when it may run unattended, and what came of it.
+ *
+ * `pal cli update` still owns the pull and the reinstall — this module only
+ * decides whether to start it and records the outcome, so the command shape
+ * lives in exactly one place.
+ *
+ * The ledger in state/auto-update.json is deliberately not update-available.json:
+ * that one is an hourly detection cache, this one is the record of what was
+ * attempted. A skip is stamped separately from an attempt so that skipping today
+ * never consumes today's attempt.
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { cachedStatus, getInstalledVersion, isRepoMode } from "../handlers/update-check";
+import { logDebug, logError } from "./log";
+import { assets, palPkg, paths } from "./paths";
+import { raw as rawSettings } from "./settings";
+
+export interface AutoUpdateLedger {
+  attemptedAt?: string;
+  finishedAt?: string;
+  ok?: boolean;
+  from?: string;
+  to?: string;
+  error?: string;
+  skippedAt?: string;
+  skipped?: string;
+}
+
+export interface AutoUpdateStatus {
+  enabled: boolean;
+  decided: boolean;
+  current: string;
+  latest: string | null;
+  available: boolean;
+  checkedAt: string | null;
+  mode: "repo" | "package";
+  last: AutoUpdateLedger | null;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DIRTY_TREE = "uncommitted changes in the PAL repo";
+
+function ledgerPath(): string {
+  return resolve(paths.state(), "auto-update.json");
+}
+
+function logPath(): string {
+  return resolve(paths.state(), "auto-update.log");
+}
+
+export function readLedger(): AutoUpdateLedger | null {
+  try {
+    const fp = ledgerPath();
+    if (!existsSync(fp)) return null;
+    return JSON.parse(readFileSync(fp, "utf-8")) as AutoUpdateLedger;
+  } catch {
+    return null;
+  }
+}
+
+function writeLedger(entry: AutoUpdateLedger): AutoUpdateLedger {
+  try {
+    writeFileSync(ledgerPath(), `${JSON.stringify(entry, null, 2)}\n`, "utf-8");
+  } catch (err) {
+    logError("auto-update:ledger", err);
+  }
+  return entry;
+}
+
+function isAutoUpdateEnabled(): boolean {
+  return rawSettings().autoUpdate?.enabled === true;
+}
+
+export function autoUpdateStatus(): AutoUpdateStatus {
+  const settings = rawSettings().autoUpdate ?? {};
+  const cache = cachedStatus();
+  return {
+    enabled: settings.enabled === true,
+    decided: settings.decided === true,
+    current: cache?.current ?? getInstalledVersion(),
+    latest: cache?.latest ?? null,
+    available: cache?.available === true,
+    checkedAt: cache?.checkedAt ?? null,
+    mode: cache?.mode ?? (isRepoMode() ? "repo" : "package"),
+    last: readLedger(),
+  };
+}
+
+/**
+ * A pull cannot fast-forward over uncommitted work, so an unattended update on a
+ * dirty clone would fail every night. It waits instead, and says so.
+ */
+function hasUncommittedChanges(): boolean {
+  if (!isRepoMode()) return false;
+  const status = spawnSync("git", ["status", "--porcelain"], {
+    cwd: palPkg(),
+    encoding: "utf-8",
+    windowsHide: true,
+  });
+  if (status.status !== 0) return false;
+  return (status.stdout ?? "").trim().length > 0;
+}
+
+function recordSkip(reason: string): void {
+  writeLedger({ ...readLedger(), skippedAt: new Date().toISOString(), skipped: reason });
+  logDebug("auto-update", `skipped: ${reason}`);
+}
+
+function attemptedWithin(ledger: AutoUpdateLedger | null, now: number): boolean {
+  if (!ledger?.attemptedAt) return false;
+  return now - new Date(ledger.attemptedAt).getTime() < DAY_MS;
+}
+
+/** The unattended gate: opted in, not already tried today, and safe to pull. */
+export function shouldAutoUpdate(now: number = Date.now()): boolean {
+  if (!isAutoUpdateEnabled()) return false;
+  if (attemptedWithin(readLedger(), now)) return false;
+  if (hasUncommittedChanges()) {
+    recordSkip(DIRTY_TREE);
+    return false;
+  }
+  return true;
+}
+
+function updateCommand(): string[] {
+  return [resolve(palPkg(), "src", "cli", "index.ts"), "cli", "update"];
+}
+
+/**
+ * Runs in the detached child, never in the hook that spawned it. The attempt is
+ * stamped before the command starts so a run that dies mid-flight still counts
+ * against today — a broken update retries tomorrow, not every session.
+ */
+export function runAutoUpdate(): AutoUpdateLedger {
+  if (hasUncommittedChanges()) {
+    recordSkip(DIRTY_TREE);
+    return readLedger() ?? {};
+  }
+
+  const from = getInstalledVersion();
+  writeLedger({ attemptedAt: new Date().toISOString(), from });
+
+  const run = spawnSync("bun", updateCommand(), {
+    cwd: palPkg(),
+    encoding: "utf-8",
+    windowsHide: true,
+  });
+  const output = `${run.stdout ?? ""}${run.stderr ?? ""}`;
+  try {
+    writeFileSync(logPath(), output, "utf-8");
+  } catch (err) {
+    logError("auto-update:log", err);
+  }
+
+  const ok = run.status === 0;
+  logDebug("auto-update", `update exited ${run.status}`);
+  return writeLedger({
+    ...readLedger(),
+    finishedAt: new Date().toISOString(),
+    ok,
+    from,
+    to: getInstalledVersion(),
+    error: ok ? undefined : (run.error?.message ?? `exit ${run.status}`),
+  });
+}
+
+/** Hands the update to its own process so session start never waits on it. */
+export function spawnAutoUpdate(): void {
+  try {
+    const child = spawn("bun", [resolve(assets.hooks(), "AutoUpdate.ts")], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.unref();
+    logDebug("auto-update", "detached update spawned");
+  } catch (err) {
+    logError("auto-update:spawn", err);
+  }
+}

package/src/hooks/lib/goal-links.ts

@@ -1,8 +1,8 @@
 /**
  * Which projects serve which stated goal, and how far along that makes it.
  *
- * The linkage needs judgement — "Catalyst is the starter that pays for the rest"
- * serves "land two retained clients" only if you know what both mean — so a model
+ * The linkage needs judgement — "the starter kit is what pays for the rest"
+ * serves "reach steady revenue" only if you know what both mean — so a model
  * draws it. The progress does not: it is criteria closed over criteria written,
  * counted here, because a model returning "64%" says something unfalsifiable
  * about a goal it cannot measure.

package/src/hooks/lib/security.ts

@@ -14,7 +14,7 @@ const WIN_RECURSE_FLAG = String.raw`(?:-(?:r(?:e(?:c(?:u(?:r(?:se?)?)?)?)?)?f?|f
 
 /**
  * A whole root, not a directory inside one. The trailing lookahead is the part
- * that matters: without it `C:\` prefix-matches `C:\Users\rico\dist` and every
+ * that matters: without it `C:\` prefix-matches `C:\Users\user\dist` and every
  * ordinary recursive delete on Windows gets blocked.
  */
 const WIN_ROOT_TARGET = String.raw`["']?(?:[a-z]:[\\/]?\*?|\\\\|~|\$home|\$env:userprofile|\$env:systemdrive)["']?(?=["'\s;,)]|$)`;

package/src/hooks/lib/settings.ts

@@ -25,6 +25,8 @@ export interface PalSettingsData {
   dynamicContext?: Record<string, boolean>;
   /** Git co-author attribution opt-in. `decided` gates the one-time prompt. */
   attribution?: { enabled?: boolean; decided?: boolean };
+  /** Daily unattended self-update opt-in. `decided` gates the one-time prompt. */
+  autoUpdate?: { enabled?: boolean; decided?: boolean };
   /**
    * Action-ledger user extension. `redactPaths` adds to the built-in set of
    * paths whose contents are never stored; it cannot shrink it.

package/src/tools/control-room/server.ts

@@ -6,6 +6,7 @@
  * `pal cli server start|stop|status` owns the process; this file only serves.
  */
 
+import { autoUpdateStatus, spawnAutoUpdate } from "../../hooks/lib/auto-update";
 import { loadMachine } from "../../hooks/lib/machine";
 import { readAllProjects } from "../../hooks/lib/projects";
 import { isServesKind, setServes } from "../../hooks/lib/serves";
@@ -25,6 +26,7 @@ import {
   isQuadrant,
   QUADRANTS,
   readInstallSettings,
+  setAutoUpdate,
   setIscStatus,
   setPlacement,
   type WriteOutcome,
@@ -255,6 +257,26 @@ async function readWrite(request: Request): Promise<Response> {
   return json({ marked: markRead(ids as string[]) });
 }
 
+async function autoUpdateWrite(request: Request): Promise<Response> {
+  const body = await readBody(request);
+  if (!body) return json({ error: "expected a JSON body" }, 400);
+  const { enabled } = body;
+  if (typeof enabled !== "boolean") {
+    return json({ error: "enabled must be true or false" }, 400);
+  }
+  const outcome = setAutoUpdate(enabled);
+  return outcome.ok ? json(autoUpdateStatus()) : answer(outcome, {});
+}
+
+/**
+ * The button runs the update the daily gate would have run, bypassing the
+ * schedule but not the dirty-tree guard the child applies to itself.
+ */
+function updateNow(): Promise<Response> {
+  spawnAutoUpdate();
+  return Promise.resolve(json({ started: true }, 202));
+}
+
 async function prefsWrite(request: Request): Promise<Response> {
   const body = await readBody(request);
   if (!body) return json({ error: "expected a JSON body" }, 400);
@@ -270,6 +292,8 @@ const WRITES: Record<string, (request: Request) => Promise<Response>> = {
   "/api/snooze": snoozeWrite,
   "/api/attention/read": readWrite,
   "/api/prefs": prefsWrite,
+  "/api/update": autoUpdateWrite,
+  "/api/update/run": updateNow,
 };
 
 export function startControlRoom(port: number = DEFAULT_PORT) {
@@ -312,6 +336,8 @@ export function startControlRoom(port: number = DEFAULT_PORT) {
           return json(readInstallSettings());
         case "/api/prefs":
           return json(readPrefs());
+        case "/api/update":
+          return json(autoUpdateStatus());
         case "/api/attention":
           return json(attention());
         case "/api/status":