portable-agent-layer 0.73.0 → 0.75.0

package/README.md

@@ -97,6 +97,7 @@ pal cli status        # check your setup
 | `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |
 | `pal cli subagent doctor <name>` | Evaluate a subagent definition against the authoring best practices (name/file match, per-platform blocks, model/tools/permission shape, shipped-name collision) |
 | `pal cli subagent list` | List the user-authored subagents in `~/.pal/agents/` |
+| `pal cli version` | Print the installed PAL version. `-v` and `--version` do the same |
 
 ### Target flags
 

package/package.json

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

package/src/cli/index.ts

@@ -17,12 +17,13 @@
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
  *   ledger <sub> [filters]            Query the action ledger (log · show · stats)
- *   server start|stop|status          The control room, a local page over ~/.pal
+ *   server start|stop|restart|status  The control room, a local page over ~/.pal
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name|--all>         Evaluate one skill, or every installed skill, against the authoring best practices
  *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
  *   subagent doctor <name>           Evaluate a subagent against the authoring best practices
  *   debug [on|off]                    Enable / disable verbose hook debug logging
+ *   version | -v                      Print the installed PAL version
  */
 
 import { spawnSync } from "node:child_process";
@@ -280,6 +281,11 @@ async function runCli(command: string | undefined, args: string[]) {
     case "debug":
       cliDebug(args);
       break;
+    case "version":
+    case "-v":
+    case "--version":
+      showVersion();
+      break;
     case "--help":
     case "-h":
     case "help":
@@ -342,7 +348,7 @@ function showHelp() {
                                             (search · graph · stats · hubs · find · show · add · ls)
     pal cli ledger <sub> [filters]          Query the action ledger (log · show · stats)
                                             e.g. ledger log --project X --since 7d
-    pal cli server start|stop|status        The control room: a local page to open before a terminal
+    pal cli server start|stop|restart|status  The control room: a local page to open before a terminal
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name|--all>       Evaluate one skill, or every installed skill
     pal cli skill author-model              Print the flagship model that authors skills for the active agent
@@ -351,6 +357,7 @@ function showHelp() {
     pal cli subagent list                   List the user-authored subagents in ~/.pal/agents/
     pal cli subagent author-model           Print the flagship model that authors subagents for the active agent
     pal cli debug [on|off]                  Enable/disable verbose hook debug logging (persisted)
+    pal cli version | -v                    Print the installed PAL version
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)
@@ -1287,9 +1294,28 @@ async function install(targets: Targets) {
     `Shared: ${indexedSkills} skills indexed · ${palDocsCount} docs → ~/.pal/docs/ · AGENTS.md + context digests written`
   );
 
+  await refreshControlRoom();
+
   log.success("Done. Existing config was preserved — only new entries were added.");
 }
 
+/**
+ * A published install carries the page in its tarball; a checkout does not —
+ * ui/dist is gitignored, so a pull leaves whatever was built last. Rebuild
+ * there, then replace the process, because the API is the running code.
+ */
+async function refreshControlRoom(): Promise<void> {
+  const { isRepoMode } = await import("../hooks/handlers/update-check");
+  const { buildPage } = await import("../tools/control-room/static");
+  if (isRepoMode() && !buildPage()) {
+    log.warn("Control room page could not be rebuilt — run: bun run build:ui");
+    return;
+  }
+
+  const { restartIfRunning } = await import("./server");
+  if (await restartIfRunning()) log.success("Control room restarted on the new build");
+}
+
 async function uninstall(args: string[]) {
   const targets = parseTargets(args);
 
@@ -1598,21 +1624,29 @@ function cliDebug(args: string[]) {
   }
 }
 
-async function status() {
-  const home = palHome();
-  const pkg = palPkg();
-
-  let pkgJson: { version: string };
+function packageVersion(): string {
   try {
-    pkgJson = JSON.parse(readFileSync(resolve(pkg, "package.json"), "utf-8")) as {
+    const pkgJson = JSON.parse(
+      readFileSync(resolve(palPkg(), "package.json"), "utf-8")
+    ) as {
       version: string;
     };
+    return pkgJson.version;
   } catch (e) {
     throw new Error(`Failed to read package.json: ${e}`);
   }
+}
+
+function showVersion() {
+  console.log(packageVersion());
+}
+
+async function status() {
+  const home = palHome();
+  const pkg = palPkg();
 
   console.log("");
-  log.info(`Version:  ${pkgJson.version}`);
+  log.info(`Version:  ${packageVersion()}`);
   log.info(`Package:  ${pkg}`);
   log.info(`Home:     ${home}`);
   console.log("");

package/src/cli/server.ts

@@ -37,6 +37,8 @@ export async function runServer(args: string[]): Promise<number> {
       return cmdStart(rest);
     case "stop":
       return cmdStop();
+    case "restart":
+      return cmdRestart();
     case "status":
       return cmdStatus();
     case undefined:
@@ -60,6 +62,7 @@ function showHelp(): void {
   Subcommands:
     start [--port <n>]         Start the control room in the background (default port ${DEFAULT_PORT})
     stop                       Stop it
+    restart                    Replace a running one — the API only changes when the process does
     status                     Show whether it is running, and where
 
   The page listens on ${LOOPBACK} only.
@@ -156,6 +159,29 @@ async function cmdStart(args: string[]): Promise<number> {
   return 0;
 }
 
+/**
+ * The page is read off disk per request, so a rebuilt dist reaches the browser
+ * on the next reload — but the API routes are the running process's own code,
+ * and those only change when the process does.
+ */
+async function cmdRestart(): Promise<number> {
+  const running = await runningServer();
+  if (!running) {
+    console.log("Not running — nothing to restart. Use `start`.");
+    return 0;
+  }
+  await cmdStop();
+  return cmdStart(["--port", String(running.port)]);
+}
+
+/**
+ * Used by `pal cli install`: an install that leaves an old build answering on
+ * the port has not finished. A server nobody started stays unstarted.
+ */
+export async function restartIfRunning(): Promise<boolean> {
+  return (await runningServer()) !== null && (await cmdRestart()) === 0;
+}
+
 /** The state file is a claim; the process answering on that port is the fact. */
 async function runningServer(): Promise<ServerState | null> {
   const state = readState();

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

@@ -46,7 +46,7 @@ function writeCache(cache: UpdateCache): void {
   }
 }
 
-function isRepoMode(): boolean {
+export function isRepoMode(): boolean {
   return existsSync(resolve(palPkg(), ".git"));
 }
 

package/src/hooks/lib/detached-inference.ts

@@ -18,15 +18,26 @@
  */
 
 import { spawn } from "node:child_process";
+import { getActiveAgent } from "./agent";
 import { logDebug, logError } from "./log";
 
+/**
+ * A hook run by Cursor, Copilot or Codex knows its agent only from the
+ * `--agent=` flag its own config put on the command line, and argv does not
+ * cross a spawn. Re-declaring it here is what stops the child from taking the
+ * "claude" default and spawning the wrong CLI for its inference.
+ */
+function withAgentDeclaration(args: string[]): string[] {
+  return [...args, `--agent=${getActiveAgent()}`];
+}
+
 export function spawnDetachedInference(
   scriptPath: string,
   args: string[],
   scope: string
 ): void {
   try {
-    const child = spawn("bun", [scriptPath, ...args], {
+    const child = spawn("bun", [scriptPath, ...withAgentDeclaration(args)], {
       detached: true,
       stdio: "ignore",
       env: { ...process.env, CLAUDECODE: undefined },

package/src/hooks/lib/readme-sync.ts

@@ -24,6 +24,14 @@ export const WATCHED_PATHS = [
   "assets/agents",
 ];
 
+/**
+ * A flag spelling of a command the README documents under its canonical name,
+ * or the `cli` prefix the dispatcher consumes before a command is ever named.
+ */
+function isAliasOrInternalRoute(cmd: string): boolean {
+  return ["--help", "-h", "help", "-v", "--version", "cli"].includes(cmd);
+}
+
 /** Extract CLI command names from the switch statement in index.ts */
 function extractCliCommands(): string[] {
   const pkg = palPkg();
@@ -36,8 +44,7 @@ function extractCliCommands(): string[] {
 
   for (const match of matches) {
     const cmd = match[1];
-    // Skip help aliases and internal routing
-    if (["--help", "-h", "help", "cli"].includes(cmd)) continue;
+    if (isAliasOrInternalRoute(cmd)) continue;
     commands.push(cmd);
   }