portable-agent-layer 0.64.0 → 0.65.0

package/README.md

@@ -32,7 +32,7 @@ With PAL, you can:
 
 > **Bun is required.** PAL is built on [Bun](https://bun.sh) and will not work with Node.js or other runtimes. Install it with `curl -fsSL https://bun.sh/install | bash`.
 
-- [Bun](https://bun.sh) >= 1.3.0
+- [Bun](https://bun.sh) >= 1.4.0
 - At least one of: [Claude Code](https://claude.ai/code), [opencode](https://opencode.ai), [Cursor](https://cursor.com), [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli), or [Codex](https://openai.com/index/introducing-codex/)
 
 ### Package mode (recommended)

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

@@ -3,7 +3,7 @@ import { createReadStream, constants as fsConstants, realpathSync } from "node:f
 import { access, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
 import { extname, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { PDFDocument } from "pdf-lib";
 import { chromium } from "playwright";
 const COLOR = {
@@ -220,7 +220,7 @@ function realResolve(p) {
     return resolve(p);
   }
 }
-const isMain = process.argv[1] && realResolve(process.argv[1]) === realResolve(new URL(import.meta.url).pathname);
+const isMain = process.argv[1] && realResolve(process.argv[1]) === realResolve(fileURLToPath(import.meta.url));
 if (isMain) {
   await run();
 }

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

@@ -19,7 +19,7 @@ import { createReadStream, constants as fsConstants, realpathSync } from "node:f
 import { access, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { createServer, type Server } from "node:http";
 import { extname, join, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { PDFDocument } from "pdf-lib";
 import { chromium } from "playwright";
 
@@ -315,6 +315,9 @@ async function run(argv: string[] = process.argv.slice(2)): Promise<void> {
 // Node ≥ 22.6 doesn't expose import.meta.main; gate on argv[1] instead.
 // Use realpathSync on both sides so symlinked skill paths (e.g. ~/.pal/skills →
 // PAL repo) match the resolved import.meta.url.
+// fileURLToPath, never new URL().pathname: on Windows the latter yields
+// "/C:/Users/..." — leading slash, forward slashes — which can never equal argv[1]'s
+// "C:\Users\...", so the gate silently failed and run() never executed there.
 function realResolve(p: string): string {
   try {
     return realpathSync(resolve(p));
@@ -324,7 +327,7 @@ function realResolve(p: string): string {
 }
 const isMain =
   process.argv[1] &&
-  realResolve(process.argv[1]) === realResolve(new URL(import.meta.url).pathname);
+  realResolve(process.argv[1]) === realResolve(fileURLToPath(import.meta.url));
 if (isMain) {
   await run();
 }

package/assets/skills/playwright/SKILL.md

@@ -26,7 +26,7 @@ Take a screenshot of a running page and `Read` it into context so you can see th
 The bundled tool picks the best available local engine automatically:
 
 1. **System `playwright-cli`** (Microsoft's stateful agent CLI) — used when it is on `PATH` and no exact viewport/full-page is requested (its `screenshot` command can't set those).
-2. **PAL-installed Playwright, launched via Node** — the cross-platform-safe path (Playwright's Chromium hangs under Bun on Windows). Honors `--viewport`, `--full-page`, and `--selector` precisely.
+2. **PAL-installed Playwright, launched in-process** — the precise path. Honors `--viewport`, `--full-page`, and `--selector` precisely.
 
 If neither engine is usable, the tool prints `NO_PLAYWRIGHT_CLI` and exits non-zero — only then use the **Playwright MCP** (tier 3) in step 4.
 
@@ -36,7 +36,7 @@ If neither engine is usable, the tool prints `NO_PLAYWRIGHT_CLI` and exits non-z
 2. Run the tool (it prints the absolute PNG path as its last stdout line):
 
    ```bash
-   node ~/.pal/skills/playwright/tools/shot.mjs <url> \
+   bun ~/.pal/skills/playwright/tools/shot.ts <url> \
      [--viewport 1440x900] [--full-page] [--selector "<css>"] [-o <out.png>]
    ```
 

package/assets/skills/playwright/tools/shot.ts

@@ -1,18 +1,17 @@
-#!/usr/bin/env node
+#!/usr/bin/env bun
 // playwright skill tool: capture a screenshot of a URL and print its absolute path.
 //
 // Engine selection (see chooseTier):
 //   Tier 1 — system `playwright-cli` binary (Microsoft's stateful agent CLI), when on
 //            PATH and no exact viewport/full-page is requested.
-//   Tier 2 — PAL-installed Playwright, launched via Node. (Playwright's chromium.launch
-//            hangs under Bun on Windows — the same Node exception create-pdf relies on.)
+//   Tier 2 — PAL-installed Playwright, launched in-process.
 // If neither engine works, prints NO_PLAYWRIGHT_CLI on stderr and exits non-zero so the
 // caller (SKILL.md) can fall back to the Playwright MCP.
 //
-// pal-build:mjs — ships as a compiled shot.mjs sibling (scripts/build-skill-tools.ts).
-// Run under Node via the compiled file (a .ts under node_modules can't be type-stripped;
-// plain .mjs needs no stripping and runs on every OS, keeping the Windows fallback):
-//   node ~/.pal/skills/playwright/tools/shot.mjs <url> [opts]
+// Runs under Bun on every OS:
+//   bun ~/.pal/skills/playwright/tools/shot.ts <url> [opts]
+// It used to ship a Node-compiled .mjs sibling because chromium.launch hung under Bun on
+// Windows; bun 1.4.0 fixes that, so the Node hop and the build step are gone.
 
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";

package/assets/skills/projects/SKILL.md

@@ -18,6 +18,9 @@ metadata:
     - "where are we"
     - "open ticket"
     - "open iscs"
+    - "file ticket"
+    - "file it as a ticket"
+    - "file a ticket"
 ---
 
 Manage the user's project registry. Each project lives at `~/.pal/memory/projects/{slug}/ISA.md`. Frontmatter holds operational state (next steps, blockers, handoff); the body holds ISA spec sections (Problem, Goal, Criteria, Context, Decisions, etc.). The Stop hook auto-touches `updated` whenever the cwd resolves into a registered project — just *being* in the project keeps it warm.
@@ -64,7 +67,7 @@ The body of each ISA.md holds spec sections. Use `update-section` to set them:
 | Decisions | `decisions` | Auto-managed by `add-decision`; dated bullet list |
 | Changelog | `changelog` | Archive of completed ISCs (`complete-isc` moves them here under a dated `### Archived` heading) plus any milestone notes |
 
-**ISC archive model.** `complete-isc` does not just check a box — it moves the ISC line out of Criteria and into the Changelog archive, so Criteria always reflects exactly the open work and never bloats the context loaded at session start. `list-isc <name>` shows open ISCs by default; pass `--closed` (archived only) or `--all` (open + archived) to read finished ones. `reopen-isc` pulls an archived ISC back into the open set. `prune-isc <name>` backfills legacy projects by sweeping any done ISCs still sitting in Criteria into the archive in one pass.
+**ISC archive model.** `complete-isc` does not just check a box — it moves the ISC line out of Criteria and into the Changelog archive, so Criteria always reflects exactly the open work and never bloats the context loaded at session start. `list-isc <name>` shows open ISCs by default; pass `--closed` (archived only) or `--all` (open + archived) to read finished ones. `reopen-isc` pulls an archived or retired ISC back into the open set. `edit-isc <name> <id> "new text"` rewrites an ISC's wording in place, keeping its id and state — use it to sharpen a vague criterion instead of closing and refiling. `retire-isc <name> <id> [--by <id>]` closes an ISC that stopped being valid: it files under a `### Retired` heading as `[~]` rather than claiming the work was done, and `--by` records the superseding ISC. A retired ISC counts as neither open nor done, is listed with `--retired`, and keeps its id reserved so no future ISC can reuse it. `prune-isc <name>` backfills legacy projects by sweeping any done ISCs still sitting in Criteria into the archive in one pass.
 
 ## Routing
 

package/assets/templates/settings.claude.json

@@ -45,7 +45,8 @@
   },
   "attribution": {
     "commit": "",
-    "pr": ""
+    "pr": "",
+    "sessionUrl": false
   },
   "showClearContextOnPlanAccept": true,
   "respectGitignore": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.64.0",
+  "version": "0.65.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.3.0"
+    "bun": ">=1.4.0"
   },
   "keywords": [
     "ai",
@@ -34,7 +34,9 @@
   },
   "scripts": {
     "type-check": "tsc --noEmit",
-    "test": "bun test",
+    "test": "bun test --randomize",
+    "test:mutate": "stryker run",
+    "test:mutate:diff": "bun .agents/scripts/mutate-diff.ts",
     "format": "biome format",
     "format-write": "biome format --write",
     "lint": "biome lint",
@@ -44,6 +46,10 @@
     "knip": "knip-bun",
     "klint": "klint",
     "jscpd": "jscpd --noTips",
+    "madge": "madge --circular --extensions ts --ts-config tsconfig.json src",
+    "lf": "bun .agents/scripts/check-lf.ts",
+    "lf:fix": "bun .agents/scripts/check-lf.ts --fix",
+    "secretlint": "secretlint \"**/*\"",
     "lint-staged": "lint-staged",
     "prepare": "bun .husky/install.mjs",
     "build:skill-tools": "bun run scripts/build-skill-tools.ts",
@@ -66,11 +72,14 @@
     "@biomejs/biome": "2.4.15",
     "@commitlint/cli": "21.0.1",
     "@commitlint/config-conventional": "21.0.1",
-    "@konvert7/klint": "0.20.0",
+    "@hughescr/stryker-bun-runner": "1.3.8",
+    "@konvert7/klint": "0.34.0",
     "@opencode-ai/plugin": "latest",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.8",
+    "@stryker-mutator/core": "9.6.1",
     "@types/adm-zip": "^0.5.8",
     "@types/bun": "latest",
     "@types/node": "latest",
@@ -78,7 +87,9 @@
     "jscpd": "^4.2.3",
     "knip": "^6.14.1",
     "lint-staged": "17.0.5",
+    "madge": "8.0.0",
     "promptfoo": "0.121.14",
+    "secretlint": "13.0.2",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3"
   },

package/src/cli/index.ts

@@ -12,7 +12,7 @@
  *   uninstall [--claude] [--opencode] [--cursor] [--codex] Remove hooks/skills for targets
  *   update                             Update PAL (git pull or npm update)
  *   export [path] [--dry-run]         Export user state to zip
- *   import [path] [--dry-run]         Import user state from zip
+ *   import [path] [--dry-run] [--overwrite]  Merge user state from zip
  *   status                            Show current PAL configuration
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
@@ -35,9 +35,17 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import {
+  appendImportLog,
+  mergeArchive,
+  readManifest,
+  summarize,
+} from "../hooks/lib/import-merge";
 import { inference, previewInferenceRoute } from "../hooks/lib/inference";
 import { DEBUG_LOG_MAX_ROTATED, logDebug } from "../hooks/lib/log";
+import { ensureRegistered, writeRegistryEntry } from "../hooks/lib/machine";
 import { palHome, palPkg, paths, platform } from "../hooks/lib/paths";
+import { auditBindings, describeBindingIssue } from "../hooks/lib/projects";
 import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 import { log } from "../targets/lib";
 import { checkPendingMigrations } from "./migrate";
@@ -274,7 +282,7 @@ function showHelp() {
     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
-    pal cli import [path] [--dry-run]       Import state from zip
+    pal cli import [path] [--dry-run]       Merge state from zip (--overwrite to replace)
     pal cli status                          Show PAL configuration
     pal cli doctor [--probe-inference]      Check prerequisites and health (--probe fires real inference per route)
     pal cli migrate [--list] [--dry-run]    Run pending data migrations
@@ -845,6 +853,16 @@ function doctor(silent = false): DoctorResult {
           );
     }
 
+    // Project bindings — where each project lives on THIS machine
+    {
+      const issues = auditBindings();
+      if (issues.length === 0) {
+        ok("Project bindings healthy");
+      } else {
+        for (const issue of issues) warn(`Binding: ${describeBindingIssue(issue)}`);
+      }
+    }
+
     // Dependencies (PAL's own npm packages)
     const nodeModulesPath = resolve(palPkg(), "node_modules");
     existsSync(nodeModulesPath)
@@ -1293,6 +1311,7 @@ async function importState(args: string[]) {
 
   const home = palHome();
   const dryRun = args.includes("--dry-run");
+  const overwrite = args.includes("--overwrite");
   const pathArg = args.find((a) => !a.startsWith("-"));
   logDebug("import", `start dryRun=${dryRun} pathArg=${pathArg ?? "(auto)"}`);
 
@@ -1369,16 +1388,83 @@ async function importState(args: string[]) {
     process.exit(0);
   }
 
-  logDebug("import", `zip=${zipPath} entries=${entries.length} dryRun=${dryRun}`);
+  logDebug(
+    "import",
+    `zip=${zipPath} entries=${entries.length} dryRun=${dryRun} overwrite=${overwrite}`
+  );
   if (dryRun) {
-    console.log(`Would import ${entries.length} files → ${home}\n`);
+    console.log(
+      `Would ${overwrite ? "overwrite with" : "merge"} ${entries.length} files → ${home}\n`
+    );
     for (const e of entries) console.log(`  ${e.entryName}`);
-  } else {
+    return;
+  }
+
+  if (overwrite) {
     zip.extractAllTo(home, true);
-    logDebug("import", `done extracted=${entries.length} to=${home}`);
-    console.log(`Imported ${entries.length} files → ${home}`);
+    logDebug("import", `done overwrote=${entries.length} to=${home}`);
+    console.log(`Imported ${entries.length} files → ${home} (overwrite)`);
+    appendImportLog(home, {
+      ts: new Date().toISOString(),
+      archive: zipPath,
+      mode: "overwrite",
+      created: 0,
+      merged: 0,
+      identical: 0,
+      conflicts: 0,
+      skipped: 0,
+      linesAdded: 0,
+      quarantineDir: null,
+    });
     log.info("Run 'pal cli install' to re-register hooks.");
+    return;
+  }
+
+  ensureRegistered(home);
+  const quarantineDir = resolve(
+    home,
+    "backups",
+    `import-conflicts-${new Date()
+      .toISOString()
+      .replace(/[-:T.]/g, "")
+      .slice(0, 14)}`
+  );
+  const result = mergeArchive(
+    entries.map((e) => ({ path: e.entryName, data: () => e.getData() })),
+    home,
+    quarantineDir
+  );
+  const source = readManifest(
+    entries.map((e) => ({ path: e.entryName, data: () => e.getData() }))
+  );
+  if (source) {
+    writeRegistryEntry({ id: source.machineId, label: source.label, os: source.os });
+    console.log(`Source machine: ${source.label} (${source.machineId})`);
+  }
+
+  appendImportLog(home, {
+    ts: new Date().toISOString(),
+    archive: zipPath,
+    mode: "merge",
+    created: result.created.length,
+    merged: result.merged.length,
+    identical: result.identical.length,
+    conflicts: result.conflicts.length,
+    skipped: result.skipped.length,
+    linesAdded: result.linesAdded,
+    quarantineDir: result.quarantineDir,
+    sourceMachineId: source?.machineId ?? null,
+  });
+
+  logDebug("import", `done merge ${summarize(result)} to=${home}`);
+  console.log(`Imported → ${home}: ${summarize(result)}`);
+  if (result.conflicts.length > 0) {
+    log.warn(
+      `${result.conflicts.length} file(s) diverged — local kept, incoming saved to ${result.quarantineDir}`
+    );
+    for (const c of result.conflicts) console.log(`  ${c}`);
   }
+  log.info("Run 'pal cli install' to re-register hooks.");
 }
 
 async function update() {

package/src/cli/migrate.ts

@@ -105,7 +105,7 @@ const v1Projects: Migration = {
 function nextIscId(criteria: string): number {
   const ids: number[] = [];
   for (const line of criteria.split("\n")) {
-    const m = new RegExp(/^-\s+\[[ x]\]\s+ISC-(\d+):/i).exec(line);
+    const m = new RegExp(/^-\s+\[[ x~]\]\s+ISC-(\d+):/i).exec(line);
     if (m) ids.push(Number(m[1]));
   }
   return ids.length > 0 ? Math.max(...ids) + 1 : 1;
@@ -117,7 +117,9 @@ function pendingThreadsForProjects(): { thread: Thread; project: ProjectProgress
   const projects = readAllProjects();
   const results: { thread: Thread; project: ProjectProgress }[] = [];
   for (const thread of threads) {
-    const project = projects.find((p) => resolve(p.path) === resolve(thread.cwd));
+    const project = projects.find(
+      (p) => p.path !== undefined && resolve(p.path) === resolve(thread.cwd)
+    );
     if (project) results.push({ thread, project });
   }
   return results;
@@ -362,7 +364,71 @@ const v3EntitiesToKnowledge: Migration = {
 
 // ── Registry ──────────────────────────────────────────────────────
 
-const MIGRATIONS: Migration[] = [v1Projects, v2ThreadsToIsc, v3EntitiesToKnowledge];
+// ── v4: project paths out of records, into machine-local bindings ──
+
+/** Records written before bindings existed carry their own `path:` in frontmatter. */
+function recordsCarryingAPath(): string[] {
+  const base = paths.projectHistory();
+  if (!existsSync(base)) return [];
+  const out: string[] = [];
+  for (const slug of readdirSync(base)) {
+    const file = resolve(base, slug, "ISA.md");
+    if (!existsSync(file)) continue;
+    const frontmatter = readFileSync(file, "utf-8").split("---")[1] ?? "";
+    if (/^path:/m.test(frontmatter)) out.push(slug);
+  }
+  return out;
+}
+
+const v4PathsToBindings: Migration = {
+  id: "v4-paths-to-bindings",
+  description: "Move project paths out of records into machine-local bindings",
+
+  check() {
+    const stale = recordsCarryingAPath();
+    return {
+      pending: stale.length > 0,
+      detail:
+        stale.length > 0 ? `${stale.length} record(s) still store a path` : undefined,
+    };
+  },
+
+  // Reading a record and writing it straight back is the whole migration: the
+  // writer already routes the path to a binding, drops the field, and picks up
+  // the git remote. Nothing here reimplements that, so the two cannot drift.
+  run(dryRun = false): MigrationResult {
+    const stale = recordsCarryingAPath();
+    const results: string[] = [];
+    let migrated = 0;
+    let skipped = 0;
+
+    for (const slug of stale) {
+      const project = readProject(slug);
+      if (!project) {
+        skipped++;
+        results.push(`${slug}: unreadable, left untouched`);
+        continue;
+      }
+      if (dryRun) {
+        migrated++;
+        results.push(`${slug}: would move ${project.path ?? "(no path)"} to a binding`);
+        continue;
+      }
+      writeProject(project);
+      migrated++;
+      results.push(`${slug}: path moved to a binding`);
+    }
+
+    return { migrated, skipped, results };
+  },
+};
+
+const MIGRATIONS: Migration[] = [
+  v1Projects,
+  v2ThreadsToIsc,
+  v3EntitiesToKnowledge,
+  v4PathsToBindings,
+];
 
 // ── Public API ────────────────────────────────────────────────────
 

package/src/hooks/lib/anchor.ts

@@ -0,0 +1,90 @@
+/**
+ * Path anchors — `{proj:slug}/relative` instead of an absolute path.
+ *
+ * An absolute cwd stamp never matches across machines: same project,
+ * different mount, different username, different OS. An anchor replaces the
+ * absolute prefix with the project's registry slug, so resolution happens
+ * locally at read time — the same trick machine.ts uses for labels, applied
+ * to paths. Relocating a project (`project.ts set-path`) then fixes every
+ * memory that ever referenced it, because none of them stored the path.
+ */
+
+import { relative, resolve, sep } from "node:path";
+import type { ProjectProgress } from "./projects";
+import {
+  projectPathOnThisMachine,
+  readAllProjects,
+  resolveProjectFromCwd,
+} from "./projects";
+
+const ANCHOR_RE = /^\{proj:([a-z0-9_-]+)\}(\/.*)?$/;
+
+export function isAnchor(value: string): boolean {
+  return ANCHOR_RE.test(value);
+}
+
+/**
+ * Absolute path → `{proj:slug}/relative`, if it falls inside a registered
+ * project. A path outside every registered project passes through
+ * unchanged — most cwd stamps from ad hoc commands will never resolve to a
+ * project, and that is fine; they simply do not benefit yet.
+ */
+export function encodeAnchor(
+  absPath: string,
+  projects: ProjectProgress[] = readAllProjects()
+): string {
+  const proj = resolveProjectFromCwd(absPath, projects);
+  if (!proj) return absPath;
+
+  // The same effective path the resolver matched on, not the record's own field:
+  // a bound project's path lives in bindings, so anchoring off proj.path directly
+  // would measure the relative segment against the wrong root.
+  const root = projectPathOnThisMachine(proj);
+  if (!root) return absPath;
+
+  const rel = relative(root, resolve(absPath));
+  if (rel.startsWith("..")) return absPath;
+
+  const relPosix = rel.split(sep).join("/");
+  return relPosix ? `{proj:${proj.name}}/${relPosix}` : `{proj:${proj.name}}`;
+}
+
+export type AnchorResolution =
+  | { state: "anchored"; path: string }
+  | { state: "plain"; path: string }
+  | { state: "unresolvable"; slug: string };
+
+/**
+ * `{proj:slug}/relative` → absolute path on THIS machine, via the local
+ * registry. A plain (non-anchor) value is returned as-is — either an
+ * already-local absolute path, or a record captured before this feature
+ * shipped. There is no backfill, so pre-anchor records are handled exactly
+ * as they were before.
+ */
+export function resolveAnchor(
+  value: string,
+  projects: ProjectProgress[] = readAllProjects()
+): AnchorResolution {
+  const match = ANCHOR_RE.exec(value);
+  if (!match) return { state: "plain", path: value };
+
+  const [, slug, rel] = match;
+  const proj = projects.find((p) => p.name === slug);
+  if (!proj) return { state: "unresolvable", slug };
+
+  const root = projectPathOnThisMachine(proj);
+  if (!root) return { state: "unresolvable", slug };
+  const path = rel ? resolve(root, `.${rel}`) : root;
+  return { state: "anchored", path };
+}
+
+/** Does `value` (anchored or plain) refer to `cwd` on this machine? */
+export function anchorMatchesCwd(
+  value: string,
+  cwd: string,
+  projects: ProjectProgress[] = readAllProjects()
+): boolean {
+  const resolved = resolveAnchor(value, projects);
+  if (resolved.state === "unresolvable") return false;
+  return resolve(resolved.path) === resolve(cwd);
+}

package/src/hooks/lib/bindings.ts

@@ -0,0 +1,117 @@
+/**
+ * Bindings — where each project lives on THIS machine.
+ *
+ * A project record answers two questions in one field today: what the project
+ * is (portable — name, goal, criteria, decisions) and where it sits on disk
+ * (true on exactly one machine). The second answer rides inside `memory/`,
+ * which is exported, so one machine's filesystem layout travels to every other
+ * machine as though it were a fact about the project.
+ *
+ * This module holds the second answer separately. Memory becomes the union of
+ * all work; bindings are one machine's intersection with its disk, so "that
+ * project is not checked out here" turns into an ordinary state rather than a
+ * dead path.
+ *
+ * `bindings.json` lives at the PAL_HOME root for the same reason `machine.json`
+ * does: export walks `telos`, `memory`, `skills` and `agents`, so anything
+ * under those would sync and defeat the point.
+ */
+
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { palHome } from "./paths";
+
+/** Project name → absolute path on this machine. */
+export type Bindings = Record<string, string>;
+
+export function bindingsFilePath(home: string = palHome()): string {
+  return resolve(home, "bindings.json");
+}
+
+/**
+ * Where the previous bindings are kept.
+ *
+ * Once a record stops storing its own path, this file is the only place a
+ * project's location lives, and it is deliberately excluded from exports — so
+ * losing it loses every location. One rolling copy of the last good content
+ * makes that recoverable by renaming a file, and never goes stale the way a
+ * one-off backup taken at migration time would.
+ */
+export function bindingsBackupPath(home: string = palHome()): string {
+  return resolve(home, "bindings.backup.json");
+}
+
+function isBindingMap(value: unknown): value is Bindings {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((v) => typeof v === "string");
+}
+
+/**
+ * A malformed or unreadable file reads as empty rather than throwing. Bindings
+ * are a lookup aid, so a corrupt one degrades to "nothing is bound here" — the
+ * same state a fresh machine starts in — instead of breaking every caller.
+ */
+export function readBindings(home: string = palHome()): Bindings {
+  const file = bindingsFilePath(home);
+  if (!existsSync(file)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf-8"));
+    if (!isBindingMap(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Seeding writes on the first project read, which makes an unsandboxed test a
+ * silent writer into the developer's own ~/.pal. The suite sets PAL_TEST_SANDBOX,
+ * so refuse there and name the file — a test that forgets to point PAL_HOME at a
+ * temp dir fails loudly instead of editing the machine running it.
+ */
+function assertNotRealHomeDuringTests(home: string): void {
+  if (!process.env.PAL_TEST_SANDBOX) return;
+  if (resolve(home) !== resolve(homedir(), ".pal")) return;
+  throw new Error(
+    "Refusing to write bindings.json into the real ~/.pal during a test run. " +
+      "Point PAL_HOME at a temp directory in this test's setup."
+  );
+}
+
+export function writeBindings(bindings: Bindings, home: string = palHome()): void {
+  assertNotRealHomeDuringTests(home);
+  const file = bindingsFilePath(home);
+  // Only a differing, non-empty predecessor is worth keeping: backing up an
+  // identical file is noise, and backing up an empty one would let a bad write
+  // erase the copy that made it recoverable.
+  if (existsSync(file) && readFileSync(file, "utf-8").trim().length > 0) {
+    copyFileSync(file, bindingsBackupPath(home));
+  }
+  const sorted: Bindings = {};
+  for (const key of Object.keys(bindings).sort()) sorted[key] = bindings[key];
+  writeFileSync(bindingsFilePath(home), `${JSON.stringify(sorted, null, 2)}\n`);
+}
+
+/** The absolute path this machine has for `project`, or null when unbound. */
+export function bindingFor(project: string, home: string = palHome()): string | null {
+  return readBindings(home)[project] ?? null;
+}
+
+/** Bind `project` to `path`, replacing any existing binding for it. */
+export function writeBinding(
+  project: string,
+  path: string,
+  home: string = palHome()
+): void {
+  const bindings = readBindings(home);
+  bindings[project] = resolve(path);
+  writeBindings(bindings, home);
+}
+
+export function removeBinding(project: string, home: string = palHome()): void {
+  const bindings = readBindings(home);
+  if (!(project in bindings)) return;
+  delete bindings[project];
+  writeBindings(bindings, home);
+}