portable-agent-layer 0.63.3 → 0.65.0

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/readme-sync.ts

@@ -79,15 +79,30 @@ function extractEnvVars(): string[] {
   return [...vars];
 }
 
-/** Extract skill names from assets/skills/ */
-function extractSkillNames(): string[] {
-  const pkg = palPkg();
-  const skillsDir = resolve(pkg, "assets", "skills");
+/**
+ * Names of the skills PAL ships — one directory per skill, each holding a
+ * SKILL.md. Reading the directory rather than loose `.md` files matters: the
+ * folder-per-skill layout is what the runtime loads, and matching on files
+ * silently yields nothing, which makes every skill check pass vacuously.
+ */
+export function shippedSkillNames(): string[] {
+  const skillsDir = resolve(palPkg(), "assets", "skills");
   if (!existsSync(skillsDir)) return [];
 
-  return readdirSync(skillsDir)
-    .filter((f) => f.endsWith(".md"))
-    .map((f) => f.replace(/\.md$/, ""));
+  return readdirSync(skillsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && existsSync(resolve(skillsDir, e.name, "SKILL.md")))
+    .map((e) => e.name)
+    .sort();
+}
+
+/**
+ * Skill names the README's "## Skills" table claims PAL ships. Scoped to that
+ * one section: other tables list commands and agents in the same row shape, and
+ * matching them would report every command as a retired skill.
+ */
+function documentedSkillNames(readme: string): string[] {
+  const section = /^## Skills$([\s\S]*?)(?=^## )/m.exec(readme)?.[1] ?? "";
+  return Array.from(section.matchAll(/^\|\s*`([a-z0-9-]+)`\s*\|/gm), (m) => m[1]);
 }
 
 /** Validate that README.md documents all code surfaces. */
@@ -118,12 +133,17 @@ export function validateReadmeSync(): SyncResult {
     }
   }
 
-  // Check skills — just verify the count is mentioned or each name appears
-  const skills = extractSkillNames();
-  const undocumentedSkills = skills.filter((name) => !readme.includes(name));
+  // Check skills — every shipped skill has a row, and no row outlives its skill
+  const shipped = shippedSkillNames();
+  const undocumentedSkills = shipped.filter((name) => !readme.includes(name));
   if (undocumentedSkills.length > 0) {
     issues.push(`Skills not documented in README: ${undocumentedSkills.join(", ")}`);
   }
 
+  const retired = documentedSkillNames(readme).filter((name) => !shipped.includes(name));
+  if (retired.length > 0) {
+    issues.push(`README documents skills that no longer ship: ${retired.join(", ")}`);
+  }
+
   return { ok: issues.length === 0, issues };
 }

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/skill-match.ts

@@ -0,0 +1,129 @@
+/**
+ * Skill matching — deterministic trigger lookup that names the skills a prompt
+ * probably wants, injected at prompt time.
+ *
+ * A skill declares its own `metadata.triggers` in SKILL.md; `generateSkillIndex`
+ * copies them into skill-index.json. Here the prompt and every trigger are
+ * normalized the same way (lowercase, punctuation to spaces, space-padded), so a
+ * plain substring test is already a whole-word test and multi-word phrases work
+ * without a regex. Pure + fail-open, like the steering classifier it rides with.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+import { isEnabled } from "./settings";
+
+interface SkillIndexEntry {
+  name: string;
+  description: string;
+  triggers?: string[];
+}
+
+export interface SkillIndex {
+  skills: Record<string, SkillIndexEntry>;
+}
+
+export interface SkillMatch {
+  name: string;
+  description: string;
+  score: number;
+  matched: string[];
+}
+
+const MAX_MATCHES = 3;
+const MAX_SKILL_BYTES = 700;
+const MAX_DESCRIPTION_CHARS = 100;
+const PHRASE_WEIGHT = 3;
+const WORD_WEIGHT = 1;
+
+/** Lowercase, punctuation to spaces, space-padded — so `includes` tests whole words. */
+function normalize(text: string): string {
+  return ` ${text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()} `;
+}
+
+function readSkillIndex(): SkillIndex | null {
+  const path = resolve(paths.state(), "skill-index.json");
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as SkillIndex;
+  } catch {
+    return null;
+  }
+}
+
+function weightOf(trigger: string): number {
+  return trigger.trim().includes(" ") ? PHRASE_WEIGHT : WORD_WEIGHT;
+}
+
+/** Rank the indexed skills whose triggers appear in the prompt, best first. */
+export function matchSkills(prompt: string, index: SkillIndex): SkillMatch[] {
+  const haystack = normalize(prompt);
+  if (haystack.trim() === "") return [];
+
+  const matches: SkillMatch[] = [];
+  for (const entry of Object.values(index.skills ?? {})) {
+    let score = 0;
+    const matched: string[] = [];
+    for (const trigger of entry.triggers ?? []) {
+      const needle = normalize(trigger);
+      if (needle.trim() === "" || !haystack.includes(needle)) continue;
+      score += weightOf(needle);
+      matched.push(trigger);
+    }
+    if (score > 0)
+      matches.push({ name: entry.name, description: entry.description, score, matched });
+  }
+
+  return matches
+    .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+    .slice(0, MAX_MATCHES);
+}
+
+function summarize(description: string): string {
+  if (description.length <= MAX_DESCRIPTION_CHARS) return description;
+  return `${description.slice(0, MAX_DESCRIPTION_CHARS).trimEnd()}…`;
+}
+
+function line(match: SkillMatch): string {
+  const matched = match.matched.map((trigger) => `"${trigger}"`).join(", ");
+  return `- ${match.name} — ${summarize(match.description)} (matched: ${matched})`;
+}
+
+/** Build the skill-match <system-reminder> for a prompt, or null if nothing matches. */
+export function getSkillReminder(prompt: string): string | null {
+  if (!isEnabled("skillMatching")) return null;
+  if (!prompt?.trim()) return null;
+
+  const index = readSkillIndex();
+  if (!index) return null;
+
+  let matches: SkillMatch[];
+  try {
+    matches = matchSkills(prompt, index);
+  } catch {
+    return null; // fail-open: never block a prompt on a matcher error
+  }
+  if (matches.length === 0) return null;
+
+  const lines: string[] = [];
+  let budget = MAX_SKILL_BYTES;
+  for (const match of matches) {
+    const rendered = line(match);
+    const cost = Buffer.byteLength(rendered);
+    if (cost > budget) break; // byte-cap: drop the overflow tail, keep top matches
+    lines.push(rendered);
+    budget -= cost;
+  }
+  if (lines.length === 0) return null;
+
+  return [
+    "<system-reminder>",
+    "Potential matching skills: these matched trigger words in your prompt. Invoke one with the Skill tool if it fits the request; ignore them if none do.",
+    ...lines,
+    "</system-reminder>",
+  ].join("\n");
+}