portable-agent-layer 0.64.0 → 0.65.0

package/src/hooks/lib/machine.ts

@@ -0,0 +1,176 @@
+/**
+ * Machine identity — who this install is, and how a record's origin becomes a
+ * name at display time.
+ *
+ * Records store the id and never the label. Resolution happens on read, so
+ * renaming a machine is a one-file edit that no stored record notices, and two
+ * machines sharing a label is a display concern rather than a data collision.
+ *
+ * `machine.json` lives at the PAL_HOME root, outside every exported directory,
+ * because importing it would give two installs one id and silently break every
+ * origin-scoped read built on top of it.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { platform as osPlatform } from "node:os";
+import { resolve } from "node:path";
+import { parse, stringify } from "./frontmatter";
+import { palHome, paths } from "./paths";
+
+export interface MachineIdentity {
+  id: string;
+  label: string;
+  os: string;
+  createdAt: string;
+}
+
+const SHORT_ID_LENGTH = 4;
+
+export function machineFilePath(home: string = palHome()): string {
+  return resolve(home, "machine.json");
+}
+
+function machinesDir(): string {
+  const dir = resolve(paths.memory(), "machines");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** First segment of the uuid — enough to disambiguate two same-labelled machines. */
+export function shortId(id: string): string {
+  return id.replaceAll("-", "").slice(0, SHORT_ID_LENGTH);
+}
+
+/**
+ * Neutral default label. Deliberately not derived from the hostname: a hostname
+ * routinely carries the owner's real name, and the label travels in every
+ * exported registry entry.
+ */
+export function defaultLabel(id: string): string {
+  return `machine-${shortId(id)}`;
+}
+
+function newIdentity(): MachineIdentity {
+  const id = crypto.randomUUID();
+  return {
+    id,
+    label: defaultLabel(id),
+    os: osPlatform(),
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function hasUsableId(value: unknown): value is Partial<MachineIdentity> & { id: string } {
+  const v = value as Partial<MachineIdentity> | null;
+  return typeof v?.id === "string" && v.id.length > 0;
+}
+
+/**
+ * Fill in whatever a stored identity is missing. Only the id is irreplaceable —
+ * discarding one orphans every record that referenced it — so a file carrying a
+ * usable id is repaired rather than regenerated.
+ */
+function repair(stored: Partial<MachineIdentity> & { id: string }): MachineIdentity {
+  return {
+    id: stored.id,
+    label: stored.label?.trim() || defaultLabel(stored.id),
+    os: stored.os || osPlatform(),
+    createdAt: stored.createdAt || new Date().toISOString(),
+  };
+}
+
+/**
+ * This install's identity, created on first call and stable afterwards. The id
+ * is never regenerated once the file exists — a changed id orphans every record
+ * that referenced the old one.
+ */
+export function loadMachine(home: string = palHome()): MachineIdentity {
+  const file = machineFilePath(home);
+  if (existsSync(file)) {
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf-8")) as unknown;
+      if (hasUsableId(parsed)) return repair(parsed);
+    } catch {
+      /* fall through to regeneration below */
+    }
+  }
+  const identity = newIdentity();
+  mkdirSync(home, { recursive: true });
+  writeFileSync(file, `${JSON.stringify(identity, null, 2)}\n`);
+  return identity;
+}
+
+/** Rename this machine. No stored record is touched — labels resolve on read. */
+export function setLabel(label: string, home: string = palHome()): MachineIdentity {
+  const current = loadMachine(home);
+  const updated = { ...current, label: label.trim() || current.label };
+  writeFileSync(machineFilePath(home), `${JSON.stringify(updated, null, 2)}\n`);
+  return updated;
+}
+
+export interface RegistryEntry {
+  id: string;
+  label: string;
+  os: string;
+}
+
+function registryPath(id: string): string {
+  return resolve(machinesDir(), `${id}.md`);
+}
+
+/** Write (or refresh) a machine's registry entry. Registry entries are exported. */
+export function writeRegistryEntry(entry: RegistryEntry, body = ""): string {
+  const file = registryPath(entry.id);
+  const existingBody = existsSync(file) ? parse(readFileSync(file, "utf-8")).body : "";
+  const content = stringify(
+    {
+      id: entry.id,
+      label: entry.label,
+      os: entry.os,
+      updated: new Date().toISOString(),
+    },
+    body || existingBody
+  );
+  writeFileSync(file, content);
+  return file;
+}
+
+/** Every known machine, this one and any that arrived via import. */
+export function readRegistry(): RegistryEntry[] {
+  const dir = machinesDir();
+  const entries: RegistryEntry[] = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".md")) continue;
+    try {
+      const meta = parse<Record<string, string>>(
+        readFileSync(resolve(dir, name), "utf-8")
+      ).meta;
+      if (meta.id && meta.label) {
+        entries.push({ id: meta.id, label: meta.label, os: meta.os ?? "" });
+      }
+    } catch {
+      /* a malformed entry must not hide the rest of the registry */
+    }
+  }
+  return entries;
+}
+
+/**
+ * Name for a record's origin id. Unknown ids fall back to the short id so a
+ * record from a machine whose entry has not arrived yet still reads sensibly.
+ * A label shared by two machines is suffixed rather than deduplicated — the
+ * registry is not always reachable, so uniqueness can never be enforced.
+ */
+export function displayName(id: string, registry: RegistryEntry[]): string {
+  const entry = registry.find((e) => e.id === id);
+  if (!entry) return shortId(id);
+  const sharesLabel = registry.some((e) => e.id !== id && e.label === entry.label);
+  return sharesLabel ? `${entry.label}·${shortId(id)}` : entry.label;
+}
+
+/** Register this install so its label can be resolved on any machine. */
+export function ensureRegistered(home: string = palHome()): MachineIdentity {
+  const identity = loadMachine(home);
+  writeRegistryEntry({ id: identity.id, label: identity.label, os: identity.os });
+  return identity;
+}

package/src/hooks/lib/projects.ts

@@ -17,14 +17,19 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, dirname, parse as parsePath, resolve, sep } from "node:path";
+import { type Bindings, readBindings, writeBinding, writeBindings } from "./bindings";
 import { parse, stringify } from "./frontmatter";
-import { paths } from "./paths";
+import { palHome, paths } from "./paths";
+import { detectRemote } from "./remote";
 
 export type ProjectStatus = "active" | "paused" | "complete" | "archived";
 
 export interface ProjectProgress {
   name: string;
-  path: string;
+  /** Resolved for this machine at read time; absent when not checked out here. */
+  path?: string;
+  /** Normalized git origin — the same on every machine, so this one does travel. */
+  remote?: string;
   status: ProjectStatus;
   created: string;
   updated: string;
@@ -109,7 +114,9 @@ const PROJECT_MARKERS = [
 
 type IsaMeta = {
   name: string;
-  path: string;
+  /** Legacy only — records written since bindings landed carry no path. */
+  path?: string;
+  remote?: string;
   status: ProjectStatus;
   created: string;
   updated: string;
@@ -188,40 +195,77 @@ export function looksLikeProjectRoot(cwd: string): boolean {
   return PROJECT_MARKERS.some((marker) => existsSync(resolve(cwdAbs, marker)));
 }
 
+/**
+ * Every project record, with `path` resolved to this machine.
+ *
+ * Seeds bindings for any project not yet bound here, which is what makes the
+ * binding file self-maintaining: no install step, no migration, no command to
+ * remember. Seeding is idempotent and writes only when it actually binds
+ * something, so the steady-state cost is the one `bindings.json` read below.
+ */
 export function readAllProjects(): ProjectProgress[] {
   const base = paths.projectHistory();
   if (!existsSync(base)) return [];
+  const bindings = readBindings();
   const out: ProjectProgress[] = [];
   for (const slug of readdirSync(base)) {
     const file = resolve(base, slug, "ISA.md");
     if (!existsSync(file)) continue;
-    const p = readProject(slug);
+    const p = readProject(slug, bindings);
     if (p) out.push(p);
   }
+  seedBindings(out);
   return out;
 }
 
-export function readProject(name: string): ProjectProgress | null {
+export function readProject(
+  name: string,
+  bindings: Bindings = readBindings()
+): ProjectProgress | null {
   const file = isaFilePath(name);
   if (!existsSync(file)) return null;
   try {
     const content = readFileSync(file, "utf-8");
     const { meta, body } = parse<IsaMeta>(content);
-    if (!meta?.name || !meta?.path || !meta?.status) return null;
-    return { ...meta, ...extractSections(body) };
+    if (!meta?.name || !meta?.status) return null;
+    // `path` is machine-local: the binding is the real source, and meta.path is
+    // only still read so records written before this change keep resolving.
+    const bound = bindings[meta.name] ?? meta.path;
+    const path = bound ? resolve(bound) : undefined;
+    return { ...meta, path, ...extractSections(body) };
   } catch {
     return null;
   }
 }
 
+/**
+ * Persist a project. The `path` is deliberately NOT written into the record:
+ * records travel in an export, and one machine's disk layout is meaningless — or
+ * actively wrong — on another. It is recorded as a binding instead, which stays
+ * on this machine. Callers keep setting `p.path` as before; only where it lands
+ * has changed.
+ */
 export function writeProject(p: ProjectProgress): void {
+  // Detected once and then kept: the remote is stable, and re-running git on
+  // every save would spawn a subprocess per project write for no new information.
+  if (!p.remote && p.path && existsSync(p.path)) {
+    const detected = detectRemote(p.path);
+    if (detected) p.remote = detected;
+  }
+  // Only a path that exists here may be bound. Saving a record is not a claim
+  // about this machine's disk — `path` may have arrived from an imported record
+  // written elsewhere, and binding it would recreate the very leak bindings exist
+  // to prevent. An explicit `writeBinding` from the user stays unguarded.
+  if (p.path && existsSync(p.path)) writeBinding(p.name, p.path);
   const meta: Record<string, unknown> = {
     name: p.name,
-    path: p.path,
     status: p.status,
     created: p.created,
     updated: p.updated,
   };
+  // Unlike `path`, this one is written into the record on purpose — it identifies
+  // the repository rather than one machine's copy of it.
+  if (p.remote) meta.remote = p.remote;
   if (p.next?.length) meta.next = p.next;
   if (p.blockers?.length) meta.blockers = p.blockers;
   if (p.handoff) meta.handoff = p.handoff;
@@ -246,18 +290,41 @@ export function deleteProject(name: string): boolean {
  * Parent-dir browse mode (cwd is an ancestor of a registered project) → null.
  * Multiple nested projects → longest registered path wins.
  */
+/**
+ * Where a project sits on THIS machine.
+ *
+ * A record's `path` is written by whichever machine last touched it and travels
+ * with the corpus, so on any other machine it is a claim rather than a fact. A
+ * binding is local by construction, so it wins; the record's path remains the
+ * fallback until this machine has bound the project.
+ *
+ * Note the fallback still trusts a foreign path — closing that is ISC-48 task 4
+ * proper, which requires seeding to be wired first.
+ */
+export function projectPathOnThisMachine(
+  project: ProjectProgress,
+  bindings: Bindings = readBindings()
+): string | null {
+  const bound = bindings[project.name] ?? project.path;
+  return bound ? resolve(bound) : null;
+}
+
 export function resolveProjectFromCwd(
   cwd: string,
-  projects: ProjectProgress[]
+  projects: ProjectProgress[],
+  bindings: Bindings = readBindings()
 ): ProjectProgress | null {
   const cwdAbs = resolve(cwd);
-  const matches = projects.filter((p) => {
-    const projAbs = resolve(p.path);
-    return cwdAbs === projAbs || cwdAbs.startsWith(projAbs + sep);
-  });
+  const matches: { project: ProjectProgress; path: string }[] = [];
+  for (const project of projects) {
+    const projAbs = projectPathOnThisMachine(project, bindings);
+    if (!projAbs) continue;
+    if (cwdAbs === projAbs || cwdAbs.startsWith(projAbs + sep))
+      matches.push({ project, path: projAbs });
+  }
   if (matches.length === 0) return null;
   matches.sort((a, b) => b.path.length - a.path.length);
-  return matches[0];
+  return matches[0].project;
 }
 
 export function isStale(
@@ -312,7 +379,8 @@ export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
   const resolved = resolveProjectFromCwd(cwd, visible);
   const projectRoot = findProjectRoot(cwd);
   const alreadyRegistered =
-    projectRoot !== null && all.some((p) => resolve(p.path) === projectRoot);
+    projectRoot !== null &&
+    all.some((p) => p.path !== undefined && resolve(p.path) === projectRoot);
   const showHint = resolved === null && projectRoot !== null && !alreadyRegistered;
 
   if (visible.length === 0 && !showHint) return "";
@@ -377,3 +445,143 @@ export function loadActiveProjectsContext(cwd: string = process.cwd()): string {
 
   return lines.join("\n");
 }
+
+/**
+ * Adopt the `path` already stored on each project record, for projects not yet
+ * bound here.
+ *
+ * Two guards keep this from importing another machine's filesystem. An existing
+ * binding always wins, because a binding is what THIS machine knows while a
+ * record's path may belong to any machine that ever wrote it. And a path is
+ * adopted only if it exists locally — that is what makes seeding safe to run on
+ * a machine that just imported someone else's corpus: their paths are simply not
+ * here, so nothing binds and those projects stay correctly unbound.
+ *
+ * Seeding is inference, so it is conservative. `writeBinding` is a statement by
+ * the user and is trusted without an existence check — binding a path you are
+ * about to clone into has to work.
+ *
+ * Returns the names newly bound, so a caller can stay silent on the common no-op.
+ */
+export function seedBindings(
+  projects: ProjectProgress[],
+  home: string = palHome()
+): string[] {
+  const bindings = readBindings(home);
+  const seeded: string[] = [];
+  for (const project of projects) {
+    if (!project.name || !project.path) continue;
+    if (project.name in bindings) continue;
+    if (!existsSync(project.path)) continue;
+    bindings[project.name] = resolve(project.path);
+    seeded.push(project.name);
+  }
+  if (seeded.length === 0) return [];
+  writeBindings(bindings, home);
+  return seeded;
+}
+
+export type BindingIssue =
+  | { kind: "unlocatable"; project: string }
+  | { kind: "missing"; project: string; path: string }
+  | { kind: "shared"; path: string; projects: string[] };
+
+/**
+ * Health of this machine's project bindings.
+ *
+ * Three things can go wrong once a path is machine-local. A project can become
+ * unlocatable, which is what losing bindings.json looks like from the outside.
+ * A binding can outlive the directory it names. And two projects can end up on
+ * one directory — the shape that appears when a name is reused for a second
+ * checkout, where binding by name alone would silently repoint the first.
+ *
+ * Read-only by construction: it reports, it never repairs.
+ */
+export function auditBindings(
+  projects: ProjectProgress[] = readAllProjects(),
+  bindings: Bindings = readBindings()
+): BindingIssue[] {
+  const issues: BindingIssue[] = [];
+  const byPath = new Map<string, string[]>();
+
+  for (const project of projects) {
+    const path = projectPathOnThisMachine(project, bindings);
+    if (!path) {
+      issues.push({ kind: "unlocatable", project: project.name });
+      continue;
+    }
+    if (!existsSync(path)) {
+      issues.push({ kind: "missing", project: project.name, path });
+      continue;
+    }
+    byPath.set(path, [...(byPath.get(path) ?? []), project.name]);
+  }
+
+  for (const [path, names] of byPath) {
+    if (names.length > 1) issues.push({ kind: "shared", path, projects: names.sort() });
+  }
+
+  return issues;
+}
+
+/**
+ * Every issue names the command that fixes it. PAL runs inside agents, where a
+ * hook cannot ask a question — so a suggestion is always a command the user can
+ * choose to run, never something applied on their behalf.
+ */
+export function describeBindingIssue(issue: BindingIssue): string {
+  const fix = (name: string) => `run 'project set-path ${name} <path>'`;
+  if (issue.kind === "unlocatable")
+    return `${issue.project} — not checked out here (${fix(issue.project)})`;
+  // "points at" rather than "bound to": the path may equally have come from a
+  // legacy record's own field, which is not a binding.
+  if (issue.kind === "missing")
+    return `${issue.project} — points at ${issue.path}, which does not exist here (${fix(issue.project)})`;
+  return `${issue.projects.join(" and ")} — both point at ${issue.path}; rebind whichever is wrong (${fix(issue.projects[0])})`;
+}
+
+export type BindingProposal = {
+  state: "unbound";
+  confidence: "strong" | "weak";
+  reason: string;
+  candidate: string;
+  command: string;
+};
+
+/**
+ * What PAL would suggest for a project it cannot locate, given where the user
+ * currently is. A matching git remote is strong evidence — two checkouts of one
+ * repository — while a matching directory name is only weak, because a name can
+ * be reused for an unrelated copy. Returns null when there is nothing worth
+ * saying, which is the common case.
+ */
+export function proposeBinding(
+  project: ProjectProgress,
+  cwd: string = process.cwd()
+): BindingProposal | null {
+  const command = `pal cli project set-path ${project.name} ${cwd}`;
+  const cwdRemote = detectRemote(cwd);
+
+  if (project.remote && cwdRemote === project.remote) {
+    return {
+      state: "unbound",
+      confidence: "strong",
+      reason: `the repository here is ${cwdRemote}, which is this project's recorded remote`,
+      candidate: cwd,
+      command,
+    };
+  }
+
+  if (basename(cwd) === project.name) {
+    return {
+      state: "unbound",
+      confidence: "weak",
+      reason:
+        "this directory shares the project's name, but nothing confirms it is the same one — a name can belong to more than one checkout",
+      candidate: cwd,
+      command,
+    };
+  }
+
+  return null;
+}

package/src/hooks/lib/relationship.ts

@@ -13,6 +13,7 @@
 
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { encodeAnchor } from "./anchor";
 import { ensureDir, paths } from "./paths";
 
 type NoteType = "W" | "O" | "Session";
@@ -65,7 +66,8 @@ export function appendNotes(notes: RelationshipNote[], sessionId?: string): void
 
   const timestamp = new Date().toTimeString().slice(0, 5);
   lines.push(`## ${timestamp}`);
-  if (sessionId) lines.push(`<!-- session:${sessionId} cwd:${process.cwd()} -->`);
+  if (sessionId)
+    lines.push(`<!-- session:${sessionId} cwd:${encodeAnchor(process.cwd())} -->`);
 
   for (const note of fresh) {
     if (note.type === "O" && note.confidence !== undefined) {

package/src/hooks/lib/remote.ts

@@ -0,0 +1,58 @@
+/**
+ * Repository identity — the one thing about a project that means the same on
+ * every machine.
+ *
+ * A path answers "where is it here", which is why it cannot travel. A git remote
+ * answers "which repository is this", which is true everywhere the repo is
+ * cloned. That makes it the portable half of a project's identity, and the
+ * evidence that lets PAL suggest a binding without guessing from a directory
+ * name — two unrelated checkouts can share a name, but not a remote.
+ *
+ * Nothing has to be committed into the repo for this to work: the remote is
+ * already there.
+ */
+
+import { spawnSync } from "node:child_process";
+
+const GIT_TIMEOUT_MS = 2000;
+
+/**
+ * SSH and HTTPS clone URLs of one repository both normalize to the same value —
+ * `git@github.com:owner/repo.git` becomes `github.com/owner/repo` — so the same
+ * repository matches however it was cloned. Any credential embedded before the
+ * host is stripped rather than stored: this value lives in a record that travels
+ * in exports.
+ */
+export function normalizeRemote(url: string): string | null {
+  const trimmed = url.trim();
+  if (!trimmed) return null;
+
+  const scp = /^[^@/]+@([^:]+):(.+)$/.exec(trimmed);
+  const withoutScheme = scp
+    ? `${scp[1]}/${scp[2]}`
+    : trimmed.replace(/^[a-z+]+:\/\//i, "");
+
+  const withoutCredentials = withoutScheme.replace(/^[^@/]*@/, "");
+  const cleaned = withoutCredentials
+    .replace(/\.git$/, "")
+    .replace(/\/+$/, "")
+    .toLowerCase();
+
+  // A remote on the local filesystem identifies nothing portable — it is just
+  // another path — so only a real host earns the right to be identity.
+  const [hostWithPort, ...rest] = cleaned.split("/");
+  const host = hostWithPort.split(":")[0];
+  if (rest.length === 0 || rest.join("/").length === 0) return null;
+  if (!/^[a-z0-9][a-z0-9-]*(\.[a-z0-9-]+)+$/.test(host)) return null;
+  return cleaned;
+}
+
+/** The normalized origin remote of the repo at `dir`, or null if there is none. */
+export function detectRemote(dir: string): string | null {
+  const res = spawnSync("git", ["-C", dir, "remote", "get-url", "origin"], {
+    encoding: "utf-8",
+    timeout: GIT_TIMEOUT_MS,
+  });
+  if (res.status !== 0 || !res.stdout) return null;
+  return normalizeRemote(res.stdout);
+}

package/src/hooks/lib/retrieval.ts

@@ -7,6 +7,8 @@
  */
 
 import { basename } from "node:path";
+import { anchorMatchesCwd } from "./anchor";
+import { readAllProjects } from "./projects";
 import type { IndexedDoc, RetrievalIndex } from "./retrieval-index";
 import { extractKeywords } from "./text-similarity";
 
@@ -87,14 +89,18 @@ function rank(query: string, index: RetrievalIndex, cwd: string): ScoredDoc[] {
     .toLowerCase()
     .replace(/[^a-z0-9-]/g, "");
   const scopeTokens = scopeKey ? extractKeywords(scopeKey) : new Set<string>();
+  // Loaded once per rank() call, not per doc — the registry rarely changes
+  // within a single retrieval pass.
+  const projects = readAllProjects();
 
   const scored: ScoredDoc[] = [];
   for (const doc of index.docs) {
     const raw = scoreDoc(queryTerms, doc, index.df, N);
     if (raw === 0) continue;
-    // Exact cwd match when available; fingerprint heuristic for older captures.
+    // Anchored or plain cwd resolved against the local registry when
+    // available; fingerprint heuristic for captures with no cwd at all.
     const scopeMatch = doc.cwd
-      ? doc.cwd === cwd
+      ? anchorMatchesCwd(doc.cwd, cwd, projects)
       : [...scopeTokens].some((t) => scopeMatches(doc, t));
     const boosted = raw * (scopeMatch ? SCOPE_BOOST : 1) * ageDecay(doc.ts);
     const confidence = boosted / self;

package/src/hooks/lib/signals.ts

@@ -1,5 +1,6 @@
 import { appendFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { loadMachine } from "./machine";
 import { paths } from "./paths";
 import { now } from "./time";
 
@@ -14,7 +15,7 @@ function emitSignal(
   filename: string,
   data: { type: string; [key: string]: unknown }
 ): void {
-  const signal: Signal = { ts: now(), ...data };
+  const signal: Signal = { ts: now(), m: loadMachine().id, ...data };
   const filepath = resolve(paths.signals(), filename);
   appendFileSync(filepath, `${JSON.stringify(signal)}\n`);
 }

package/src/hooks/lib/stop.ts

@@ -3,6 +3,7 @@
  * Used by StopOrchestrator.ts (Claude Code) and opencode plugin.
  */
 
+import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { mkdtemp, rename, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -189,8 +190,10 @@ async function detachFailurePrinciple(transcript: string): Promise<void> {
   // Rename to claim the pending file atomically — prevents two Stop hooks
   // racing on the same low rating (opencode notably fires session.idle AND
   // session.diff concurrently, so runStopHandlers runs twice in parallel).
-  const claimedDir = await mkdtemp(resolve(tmpdir(), "pal-pending-"));
-  const claimedPath = resolve(claimedDir, "pending.json");
+  // The claim stays inside the state directory: rename fails with EXDEV across
+  // devices, and the OS temp dir is on another volume often enough to matter.
+  const claimId: string = randomUUID();
+  const claimedPath = resolve(paths.state(), `pending-failure.${claimId}.json`);
   try {
     await rename(pendingPath, claimedPath);
   } catch (err) {