@haywoodmarx/agent-pager 0.1.0 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Haywood-Marx
+Copyright (c) 2026 Paul Haywood-Marx
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -17,14 +17,22 @@ A send commits before its wake is published. Every session registers the address
 
 Implementation metadata is open and opaque. The neutral runtime discovers provider manifests by convention, and shared launch or notification code resolves capabilities through `ImplementationRegistry` rather than switching on provider ids.
 
-Pager runs on Bun, at or above the release named by `packageManager` in `package.json`, and requires it on `PATH`. Embedded GUI hosts that do not inherit the interactive shell environment require `PAGER_BUN_PATH` to name the validated absolute Bun executable. The store directory and every path derived from it are resolved for macOS only; the CLI refuses to start on another platform.
+Pager runs on Bun, at or above the release named by `packageManager` in `package.json`, and requires it on `PATH`. Embedded GUI hosts that do not inherit the interactive shell environment require `PAGER_BUN_PATH` to name the validated absolute Bun executable. An installer that keeps each version in its own directory sets `PAGER_PACKAGE_ROOT` to a path of the package root that survives its upgrades, and Pager names its entry points through that path in the files it writes for a host to run. The store directory and every path derived from it are resolved for macOS only; the CLI refuses to start on another platform.
 
 ## Install
 
+```sh
+brew install haywoodmarx/tap/agent-pager
+```
+
+Or with npm:
+
 ```sh
 npm install -g @haywoodmarx/agent-pager
 ```
 
+Some harnesses need a plugin before sessions you start without `pager` can join the broker. To install one, open `pager`, press `m`, and choose it under Install plugins.
+
 ## Install from a local checkout
 
 ```sh
@@ -58,6 +66,6 @@ The broker starts on demand: `pager` with no command, and every harness connecti
 
 Callers adopt a running service only when its database-adjacent lock and `/health` agree on the service identity; concurrent starters race for that lock and every caller adopts the winner. The adoption rules are declared in [`src/launch/on-demand.ts`](src/launch/on-demand.ts) and [`src/launch/broker-lock.ts`](src/launch/broker-lock.ts).
 
-Back up the database and active service plist before an upgrade if their current state matters. Schema changes are destructive: a database whose schema marker or required columns do not match the running build is recreated, discarding every identity and message it held, and the recreation is reported with the counts it deleted on the standard error of the command that started the service, whether that is `pager serve` or an on-demand start. The marker is part of the service adoption identity, so a build that would recreate the database cannot displace a running service that owns it. Deleting the database and starting the service also creates an empty broker. After `uninstall`, delete the retained `.previous` plist and database only when rollback and message recovery are no longer required.
+Back up the database before an upgrade if its current state matters. Schema changes are destructive: a database whose schema marker or required columns do not match the running build is recreated, discarding every identity and message it held, and the recreation is reported with the counts it deleted on the standard error of the command that started the service, whether that is `pager serve` or an on-demand start. The marker is part of the service adoption identity, so a build that would recreate the database cannot displace a running service that owns it. Deleting the database and starting the service also creates an empty broker.
 
 Per-implementation installation and conformance documentation is indexed under [`docs/implementations/acceptance/`](docs/implementations/acceptance/README.md).

package/dist/src/implementations/claude/manifest.js

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { resolvePagerStoreDirectory } from "../../configuration.js";
 import { packagedSkillPath } from "../../launch/skill.js";
-import { resolveBunExecutable, stableBunExecutable } from "../../launch/runtime.js";
+import { resolveBunExecutable, stableBunExecutable, stablePackagePath } from "../../launch/runtime.js";
 import { implementationId } from "../registry.js";
 import { CLAUDE_BROKER_URL_ENVIRONMENT, CLAUDE_MESSAGING_RESERVATION_ENVIRONMENT } from "./environment.js";
 import { claudePluginRegistrationCommand, createClaudePluginPort } from "./plugin-directory.js";
@@ -85,7 +85,7 @@ function systemPluginPort() {
     // Discovery imports this manifest on every platform and before Bun is necessarily resolvable, so
     // the store path and runtime are resolved on first use rather than at module load.
     let resolved;
-    const port = () => (resolved ??= createClaudePluginPort(join(resolvePagerStoreDirectory(process.platform, homedir()), "claude-plugin"), stableBunExecutable(resolveBunExecutable()), packagedSkillPath));
+    const port = () => (resolved ??= createClaudePluginPort(join(resolvePagerStoreDirectory(process.platform, homedir()), "claude-plugin"), stableBunExecutable(resolveBunExecutable()), (entryPath) => stablePackagePath(entryPath), packagedSkillPath));
     return {
         ensurePlugin: () => port().ensurePlugin(),
     };

package/dist/src/implementations/claude/plugin-directory.d.ts

@@ -33,11 +33,13 @@ export type ClaudePluginFileSystem = {
  * validated Bun executable and this installation's entry points by absolute path.
  * @param root - Directory the plugin is written into.
  * @param runtimePath - Absolute Bun executable that runs the generated entry points.
+ * @param stablePath - Maps one of this installation's entry points to the absolute path the plugin
+ * names it by, which must outlive an upgrade of the installation.
  * @param skillPath - Locates the packaged skill directory whose `SKILL.md` the plugin ships.
  * @param files - Filesystem seam used for the module's own isolation.
  * @returns - Port that writes the generated plugin directory.
  */
-export declare function createClaudePluginPort(root: string, runtimePath: string, skillPath: () => string, files?: ClaudePluginFileSystem): ClaudePluginPort;
+export declare function createClaudePluginPort(root: string, runtimePath: string, stablePath: (entryPath: string) => string, skillPath: () => string, files?: ClaudePluginFileSystem): ClaudePluginPort;
 /**
  * Build the plugin manifest Claude reads to name this integration and reach its channel tools.
  *
@@ -75,6 +77,7 @@ export declare function claudePluginMarketplace(): Record<string, unknown>;
  * The `hooks` wrapper is required. A document that omits it is accepted silently and no hook ever
  * runs, which presents as a session that looks healthy and never wakes.
  * @param runtimePath - Absolute Bun executable that runs the hook entry point.
+ * @param sessionStartPath - Absolute session start entry point the hook runs.
  * @returns - Hook document for the generated plugin.
  */
-export declare function claudePluginHooks(runtimePath: string): Record<string, unknown>;
+export declare function claudePluginHooks(runtimePath: string, sessionStartPath: string): Record<string, unknown>;

package/dist/src/implementations/claude/plugin-directory.js

@@ -24,11 +24,13 @@ const sessionStartEntryPath = fileURLToPath(new URL("./session-start-cli.js", im
  * validated Bun executable and this installation's entry points by absolute path.
  * @param root - Directory the plugin is written into.
  * @param runtimePath - Absolute Bun executable that runs the generated entry points.
+ * @param stablePath - Maps one of this installation's entry points to the absolute path the plugin
+ * names it by, which must outlive an upgrade of the installation.
  * @param skillPath - Locates the packaged skill directory whose `SKILL.md` the plugin ships.
  * @param files - Filesystem seam used for the module's own isolation.
  * @returns - Port that writes the generated plugin directory.
  */
-export function createClaudePluginPort(root, runtimePath, skillPath, files = systemFileSystem()) {
+export function createClaudePluginPort(root, runtimePath, stablePath, skillPath, files = systemFileSystem()) {
     const manifestPath = join(root, ".claude-plugin", "plugin.json");
     const marketplacePath = join(root, ".claude-plugin", "marketplace.json");
     const hooksPath = join(root, "hooks", "hooks.json");
@@ -41,9 +43,11 @@ export function createClaudePluginPort(root, runtimePath, skillPath, files = sys
             // Remove a stale monitors document: Claude loads whatever the directory holds, and one left
             // over would arm a monitor that fails at every session start.
             files.removeFile(retiredMonitorsPath);
-            files.writeFile(manifestPath, `${JSON.stringify(claudePluginManifest(runtimePath, gatewayPath), null, 2)}\n`);
+            const manifest = claudePluginManifest(runtimePath, stablePath(gatewayPath));
+            const hooks = claudePluginHooks(runtimePath, stablePath(sessionStartEntryPath));
+            files.writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
             files.writeFile(marketplacePath, `${JSON.stringify(claudePluginMarketplace(), null, 2)}\n`);
-            files.writeFile(hooksPath, `${JSON.stringify(claudePluginHooks(runtimePath), null, 2)}\n`);
+            files.writeFile(hooksPath, `${JSON.stringify(hooks, null, 2)}\n`);
             files.writeFile(skillDocumentPath, files.readFile(join(skillPath(), "SKILL.md")));
             return root;
         },
@@ -109,12 +113,13 @@ export function claudePluginMarketplace() {
  * The `hooks` wrapper is required. A document that omits it is accepted silently and no hook ever
  * runs, which presents as a session that looks healthy and never wakes.
  * @param runtimePath - Absolute Bun executable that runs the hook entry point.
+ * @param sessionStartPath - Absolute session start entry point the hook runs.
  * @returns - Hook document for the generated plugin.
  */
-export function claudePluginHooks(runtimePath) {
+export function claudePluginHooks(runtimePath, sessionStartPath) {
     return {
         hooks: {
-            SessionStart: [{ hooks: [{ type: "command", command: shellCommand(runtimePath, sessionStartEntryPath) }] }],
+            SessionStart: [{ hooks: [{ type: "command", command: shellCommand(runtimePath, sessionStartPath) }] }],
         },
     };
 }

package/dist/src/launch/broker-lock.js

@@ -9,7 +9,7 @@ import { satisfiesBunVersionFloor } from "./runtime.js";
 /** Identifies the ownership schema understood by this release. */
 export const SERVICE_PROTOCOL_VERSION = 1;
 /** Identifies the package build that owns production service state. */
-export const SERVICE_BUILD_ID = `agent-pager@${PAGER_VERSION}`;
+export const SERVICE_BUILD_ID = `@haywoodmarx/agent-pager@${PAGER_VERSION}`;
 /** Identifies the production runtime required to own SQLite. */
 export const SERVICE_RUNTIME = "bun";
 /**

package/dist/src/launch/runtime.d.ts

@@ -3,6 +3,8 @@ import { type RuntimeEnvironment } from "./environment.js";
 export declare const MINIMUM_BUN_VERSION = "1.4.2";
 /** Names the environment variable that pins an explicit Bun executable for spawned services. */
 export declare const BUN_PATH_ENVIRONMENT = "PAGER_BUN_PATH";
+/** Names the environment variable an installer sets to a path of this package's root that outlives its upgrades. */
+export declare const PACKAGE_ROOT_ENVIRONMENT = "PAGER_PACKAGE_ROOT";
 /** Names the Node runtime override variable; `resolveBunExecutable` rejects it whenever it holds a non-empty value. */
 export declare const RETIRED_NODE_PATH_ENVIRONMENT = "PAGER_NODE_PATH";
 /** Raised when no executable satisfying the Bun runtime policy can be selected. */
@@ -64,6 +66,19 @@ export declare function resolveBunExecutable(environment?: NodeJS.ProcessEnv, ov
  * @returns - First `bun` on the search path that resolves to the same file, or the executable itself.
  */
 export declare function stableBunExecutable(executable: string, searchPath?: readonly string[], realPath?: (path: string) => string): string;
+/**
+ * Prefer the package root an installer keeps at a stable path over the versioned directory it links to.
+ *
+ * A path written into a long-lived file must outlive an upgrade. Homebrew, for one, keeps each
+ * version in a directory the next upgrade deletes, and Bun runs a module from its resolved path, so
+ * the module's own location names that directory even when it was started through the stable link.
+ * @param entryPath - Absolute path of a file in this package, as the module that owns it sees it.
+ * @param environment - Process environment naming the stable package root.
+ * @param realPath - Resolves symbolic links; overridden by isolated verification.
+ * @returns - The same file under the stable root when that root resolves to a directory holding it,
+ * or the entry path itself.
+ */
+export declare function stablePackagePath(entryPath: string, environment?: NodeJS.ProcessEnv, realPath?: (path: string) => string): string;
 /**
  * Resolve and pin the standalone Bun executable before an embedded host starts a service.
  * @param processEnvironment - Environment inherited by the editor host.

package/dist/src/launch/runtime.js

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { accessSync, constants, realpathSync } from "node:fs";
-import { delimiter, isAbsolute, resolve } from "node:path";
+import { delimiter, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { readRuntimeEnvironment } from "./environment.js";
 /** Bounds one probe of an external runtime executable. */
 const RUNTIME_PROBE_TIMEOUT_MS = 10_000;
@@ -8,6 +8,8 @@ const RUNTIME_PROBE_TIMEOUT_MS = 10_000;
 export const MINIMUM_BUN_VERSION = "1.4.2";
 /** Names the environment variable that pins an explicit Bun executable for spawned services. */
 export const BUN_PATH_ENVIRONMENT = "PAGER_BUN_PATH";
+/** Names the environment variable an installer sets to a path of this package's root that outlives its upgrades. */
+export const PACKAGE_ROOT_ENVIRONMENT = "PAGER_PACKAGE_ROOT";
 /** Names the Node runtime override variable; `resolveBunExecutable` rejects it whenever it holds a non-empty value. */
 export const RETIRED_NODE_PATH_ENVIRONMENT = "PAGER_NODE_PATH";
 /** Raised when no executable satisfying the Bun runtime policy can be selected. */
@@ -119,6 +121,34 @@ export function stableBunExecutable(executable, searchPath = defaultProbe().sear
     }
     return executable;
 }
+/**
+ * Prefer the package root an installer keeps at a stable path over the versioned directory it links to.
+ *
+ * A path written into a long-lived file must outlive an upgrade. Homebrew, for one, keeps each
+ * version in a directory the next upgrade deletes, and Bun runs a module from its resolved path, so
+ * the module's own location names that directory even when it was started through the stable link.
+ * @param entryPath - Absolute path of a file in this package, as the module that owns it sees it.
+ * @param environment - Process environment naming the stable package root.
+ * @param realPath - Resolves symbolic links; overridden by isolated verification.
+ * @returns - The same file under the stable root when that root resolves to a directory holding it,
+ * or the entry path itself.
+ */
+export function stablePackagePath(entryPath, environment = process.env, realPath = realpathSync) {
+    const stableRoot = environment[PACKAGE_ROOT_ENVIRONMENT];
+    if (!stableRoot)
+        return entryPath;
+    if (!isAbsolute(stableRoot))
+        throw new Error(`${PACKAGE_ROOT_ENVIRONMENT} must name an absolute directory`);
+    const resolvedRoot = tryRealPath(stableRoot, realPath);
+    const resolvedEntry = tryRealPath(entryPath, realPath);
+    if (resolvedRoot === undefined || resolvedEntry === undefined)
+        return entryPath;
+    const entryWithinRoot = relative(resolvedRoot, resolvedEntry);
+    if (entryWithinRoot === ".." || entryWithinRoot.startsWith(`..${sep}`) || isAbsolute(entryWithinRoot)) {
+        return entryPath;
+    }
+    return join(stableRoot, entryWithinRoot);
+}
 function tryRealPath(path, realPath) {
     try {
         return realPath(path);

package/dist/src/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * Read the version a package manifest declares.
  *
- * Throws for a manifest without one, which would otherwise build `agent-pager@undefined`.
+ * Throws for a manifest without one.
  * @param contents - Manifest text as read from disk.
  * @param source - Manifest path named in the rejection.
  * @returns - The declared version.

package/dist/src/version.js

@@ -5,7 +5,7 @@ import { isPlainObject } from "./shared/guards.js";
 /**
  * Read the version a package manifest declares.
  *
- * Throws for a manifest without one, which would otherwise build `agent-pager@undefined`.
+ * Throws for a manifest without one.
  * @param contents - Manifest text as read from disk.
  * @param source - Manifest path named in the rejection.
  * @returns - The declared version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haywoodmarx/agent-pager",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Durable local messaging between agent implementations.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -38,6 +38,7 @@
   "scripts": {
     "prepare": "bun install --frozen-lockfile --ignore-scripts && bun run build && husky",
     "build": "bun scripts/tooling/build.mjs",
+    "release": "bun scripts/tooling/release.mjs",
     "prepack": "bun run build",
     "check:client-boundary": "bun scripts/tooling/client-boundary-self-test.mjs && bun scripts/tooling/client-boundary.mjs",
     "check:broker-writes": "bun scripts/tooling/broker-writes-self-test.mjs && bun scripts/tooling/broker-writes.mjs",
@@ -99,7 +100,7 @@
     "orchestration",
     "pi-package"
   ],
-  "author": "Haywood-Marx",
+  "author": "Paul Haywood-Marx",
   "license": "MIT",
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "*",