portable-agent-layer 0.64.0 → 0.65.0

package/src/targets/lib.ts

@@ -50,14 +50,20 @@ export function writeJson(path: string, data: unknown): void {
 /** Public PAL repository — the link surfaced in commit/PR co-author credits. */
 export const PAL_REPO_URL = "https://github.com/kovrichard/portable-agent-layer";
 
-/** Build the commit footer (bare URL, autolinks on GitHub) and PR body line (markdown link). */
+/**
+ * Build the commit footer (bare URL, autolinks on GitHub) and PR body line
+ * (markdown link). `sessionUrl` is off because Claude Code otherwise appends a
+ * claude.ai session link to commits made from web or Remote Control sessions,
+ * which puts a link to a private transcript in a public history.
+ */
 export function buildAttributionText(
   name: string,
   repoUrl: string = PAL_REPO_URL
-): { commit: string; pr: string } {
+): { commit: string; pr: string; sessionUrl: false } {
   return {
     commit: `Co-authored by ${name} · ${repoUrl}`,
     pr: `Co-authored by [${name}](${repoUrl})`,
+    sessionUrl: false,
   };
 }
 
@@ -75,7 +81,7 @@ export function applyAttribution(
     result.attribution = buildAttributionText(opts.name, opts.repoUrl);
     result.includeCoAuthoredBy = false;
   } else {
-    result.attribution = { commit: "", pr: "" };
+    result.attribution = { commit: "", pr: "", sessionUrl: false };
     if (result.includeCoAuthoredBy === false) delete result.includeCoAuthoredBy;
   }
   return result;
@@ -693,8 +699,8 @@ export function scaffoldPalSettings(): void {
 
 // --- PAL docs (modular context routing files) ---
 
-const PAL_DOCS_DIR = resolve(palHome(), "docs");
-const PAL_TOOLS_DIR = resolve(palHome(), "tools");
+const palDocsDir = () => resolve(palHome(), "docs");
+const palToolsDir = () => resolve(palHome(), "tools");
 
 /**
  * Install PAL system docs into ~/.pal/docs/.
@@ -705,19 +711,19 @@ export function copyPalDocs(): number {
   const srcDir = assets.palDocs();
   if (!existsSync(srcDir)) return 0;
 
-  mkdirSync(PAL_DOCS_DIR, { recursive: true });
+  mkdirSync(palDocsDir(), { recursive: true });
   let count = 0;
 
   for (const file of readdirSync(srcDir).filter((f) => f.endsWith(".md"))) {
     const src = resolve(srcDir, file);
-    const dst = resolve(PAL_DOCS_DIR, file);
+    const dst = resolve(palDocsDir(), file);
     copyFileSync(src, dst);
     count++;
   }
 
   // ~/.pal/tools/ → repo agent tools
   const linkType = process.platform === "win32" ? "junction" : "dir";
-  ensureSymlink(PAL_TOOLS_DIR, assets.agentTools(), linkType);
+  ensureSymlink(palToolsDir(), assets.agentTools(), linkType);
 
   return count;
 }
@@ -726,13 +732,13 @@ export function copyPalDocs(): number {
 export function removePalDocs(): void {
   // Remove tools symlink
   try {
-    unlinkSync(PAL_TOOLS_DIR);
+    unlinkSync(palToolsDir());
   } catch {
     /* gone */
   }
-  if (!existsSync(PAL_DOCS_DIR)) return;
+  if (!existsSync(palDocsDir())) return;
   try {
-    rmSync(PAL_DOCS_DIR, { recursive: true });
+    rmSync(palDocsDir(), { recursive: true });
     log.info("Removed ~/.pal/docs/");
   } catch {
     /* gone */
@@ -741,7 +747,7 @@ export function removePalDocs(): void {
 
 // --- Skills ---
 
-const PAL_SKILLS_DIR = resolve(palHome(), "skills");
+const palSkillsDir = () => resolve(palHome(), "skills");
 
 /**
  * Run one step of a bulk install, naming it only when it fails.
@@ -772,7 +778,7 @@ export function copySkills(claudeSkillsDir: string): number {
   const skillsDir = assets.skills();
   if (!existsSync(skillsDir)) return 0;
 
-  mkdirSync(PAL_SKILLS_DIR, { recursive: true });
+  mkdirSync(palSkillsDir(), { recursive: true });
   mkdirSync(claudeSkillsDir, { recursive: true });
   const linkType = process.platform === "win32" ? "junction" : "dir";
   let count = 0;
@@ -785,7 +791,7 @@ export function copySkills(claudeSkillsDir: string): number {
     const srcDir = resolve(skillsDir, name);
     if (!existsSync(resolve(srcDir, "SKILL.md"))) continue;
 
-    const palLink = resolve(PAL_SKILLS_DIR, name);
+    const palLink = resolve(palSkillsDir(), name);
     const claudeLink = resolve(claudeSkillsDir, name);
     const linked = reportOnlyOnFailure(`skill ${name}`, () => {
       // ~/.pal/skills/<name> → <repo>/assets/skills/<name>
@@ -798,7 +804,7 @@ export function copySkills(claudeSkillsDir: string): number {
 
   // ~/.agents/skills/ → ~/.pal/skills/
   mkdirSync(platform.agentsDir(), { recursive: true });
-  ensureSymlink(resolve(platform.agentsDir(), "skills"), PAL_SKILLS_DIR, linkType);
+  ensureSymlink(resolve(platform.agentsDir(), "skills"), palSkillsDir(), linkType);
 
   return count;
 }
@@ -836,8 +842,8 @@ function symlinkPointsInto(link: string, root: string): boolean {
  */
 function pruneStaleSkillLinks(agentSkillsDir: string): string[] {
   const ownedTrees = [
-    { dir: PAL_SKILLS_DIR, root: assets.skills() },
-    { dir: agentSkillsDir, root: PAL_SKILLS_DIR },
+    { dir: palSkillsDir(), root: assets.skills() },
+    { dir: agentSkillsDir, root: palSkillsDir() },
   ];
   const removed: string[] = [];
   for (const { dir, root } of ownedTrees) {
@@ -878,7 +884,7 @@ function perSkillAgentDirs(): { agent: string; dir: string }[] {
  * is covered by the whole-dir ~/.agents/skills link).
  */
 export function linkPersonalSkill(name: string): string[] {
-  const palLink = resolve(PAL_SKILLS_DIR, name);
+  const palLink = resolve(palSkillsDir(), name);
   if (!existsSync(resolve(palLink, "SKILL.md"))) {
     throw new Error(`No skill found at ${palLink}/SKILL.md`);
   }
@@ -892,8 +898,47 @@ export function linkPersonalSkill(name: string): string[] {
   return linked;
 }
 
+/**
+ * The agent config trees PAL writes into when no env override is set. These are
+ * the developer's own installed agents, so a test that forgets to point the
+ * PAL_*_DIR vars at a sandbox silently rewires their real setup.
+ */
+function realAgentRoots(): string[] {
+  const h = homedir();
+  return [
+    resolve(h, ".pal"),
+    resolve(h, ".claude"),
+    resolve(h, ".cursor"),
+    resolve(h, ".copilot"),
+    resolve(h, ".codex"),
+    resolve(h, ".agents"),
+    resolve(h, ".config", "opencode"),
+  ];
+}
+
+/**
+ * Under `bun test` (PAL_TEST_SANDBOX, set by the test preload and inherited by
+ * spawned CLIs), refuse any link that would land in a real agent tree. Tests
+ * sandbox PAL_HOME far more reliably than they sandbox the per-agent dirs, and
+ * the failure is otherwise invisible: the suite passes while the developer's
+ * own agents accumulate links into a deleted test directory.
+ */
+function assertInsideTestSandbox(link: string): void {
+  if (!process.env.PAL_TEST_SANDBOX) return;
+  const escaped = realAgentRoots().find(
+    (root) => link === root || link.startsWith(root + sep)
+  );
+  if (!escaped) return;
+  throw new Error(
+    `Refusing to write ${link}: outside the test sandbox (${escaped} is a real agent directory). ` +
+      "Point PAL_CLAUDE_DIR, PAL_CURSOR_DIR, PAL_COPILOT_DIR, PAL_CODEX_DIR, " +
+      "PAL_OPENCODE_DIR and PAL_AGENTS_DIR at a temp directory in this test."
+  );
+}
+
 /** Create or update a symlink/junction, replacing any non-symlink entry. */
 function ensureSymlink(link: string, target: string, type: "dir" | "junction"): void {
+  assertInsideTestSandbox(link);
   try {
     const st = lstatSync(link);
     if (st.isSymbolicLink()) return; // already a symlink, leave it
@@ -941,7 +986,7 @@ export function removeSkills(claudeSkillsDir: string): string[] {
   for (const name of readdirSync(skillsDir)) {
     if (!existsSync(resolve(skillsDir, name, "SKILL.md"))) continue;
 
-    for (const link of [resolve(PAL_SKILLS_DIR, name), resolve(claudeSkillsDir, name)]) {
+    for (const link of [resolve(palSkillsDir(), name), resolve(claudeSkillsDir, name)]) {
       try {
         unlinkSync(link);
       } catch {
@@ -964,14 +1009,14 @@ export function removeSkills(claudeSkillsDir: string): string[] {
 
 // --- Agents ---
 
-const CLAUDE_AGENTS_DIR = resolve(platform.claudeDir(), "agents");
+const claudeAgentsDir = () => resolve(platform.claudeDir(), "agents");
 
 /**
  * Install PAL agent definitions into ~/.claude/agents/.
  * Always overwrites — engine-managed, not user-editable.
  */
 export function copyAgents(): number {
-  return installAgents(CLAUDE_AGENTS_DIR, "claude");
+  return installAgents(claudeAgentsDir(), "claude");
 }
 
 /** Remove PAL agents from ~/.claude/agents/ */
@@ -981,7 +1026,7 @@ export function removeAgents(): string[] {
 
   const removed: string[] = [];
   for (const file of readdirSync(agentsDir).filter((f) => f.endsWith(".md"))) {
-    const dst = resolve(CLAUDE_AGENTS_DIR, file);
+    const dst = resolve(claudeAgentsDir(), file);
     if (existsSync(dst)) {
       unlinkSync(dst);
       const name = file.replace(/\.md$/, "");
@@ -994,9 +1039,9 @@ export function removeAgents(): string[] {
 
 /** Count agent .md files in ~/.claude/agents/ */
 export function countAgents(): number {
-  if (!existsSync(CLAUDE_AGENTS_DIR)) return 0;
+  if (!existsSync(claudeAgentsDir())) return 0;
   try {
-    return readdirSync(CLAUDE_AGENTS_DIR).filter((f) => f.endsWith(".md")).length;
+    return readdirSync(claudeAgentsDir()).filter((f) => f.endsWith(".md")).length;
   } catch {
     return 0;
   }
@@ -1132,7 +1177,7 @@ export function removeAgentsFromCopilot(copilotAgentsDir: string): string[] {
  * Store for user-authored subagents: ~/.pal/agents/<name>.md — one merged
  * multi-platform frontmatter file per subagent (same schema as assets/agents/).
  */
-const PAL_AGENTS_STORE = resolve(palHome(), "agents");
+const palAgentsStore = () => resolve(palHome(), "agents");
 
 /**
  * Each installed agent and the native agents directory a personal subagent is
@@ -1161,8 +1206,8 @@ function shippedAgentNames(): Set<string> {
 
 /** List the user-authored subagents in ~/.pal/agents/. */
 export function listPersonalSubagents(): string[] {
-  if (!existsSync(PAL_AGENTS_STORE)) return [];
-  return readdirSync(PAL_AGENTS_STORE)
+  if (!existsSync(palAgentsStore())) return [];
+  return readdirSync(palAgentsStore())
     .filter((f) => f.endsWith(".md"))
     .map((f) => f.replace(/\.md$/, ""))
     .sort();
@@ -1176,7 +1221,7 @@ export function listPersonalSubagents(): string[] {
  * its own frontmatter shape. Returns the agents it was installed into.
  */
 export function installPersonalSubagent(name: string): string[] {
-  const src = resolve(PAL_AGENTS_STORE, `${name}.md`);
+  const src = resolve(palAgentsStore(), `${name}.md`);
   if (!existsSync(src)) {
     throw new Error(`No subagent found at ${src}`);
   }
@@ -1408,7 +1453,7 @@ function extractTriggers(description: string): string[] {
  * Called during install after skills are symlinked.
  */
 export function generateSkillIndex(): number {
-  if (!existsSync(PAL_SKILLS_DIR)) return 0;
+  if (!existsSync(palSkillsDir())) return 0;
 
   const index: SkillIndex = {
     generated: new Date().toISOString(),
@@ -1416,8 +1461,8 @@ export function generateSkillIndex(): number {
     skills: {},
   };
 
-  for (const name of readdirSync(PAL_SKILLS_DIR)) {
-    const skillMd = resolve(PAL_SKILLS_DIR, name, "SKILL.md");
+  for (const name of readdirSync(palSkillsDir())) {
+    const skillMd = resolve(palSkillsDir(), name, "SKILL.md");
     if (!existsSync(skillMd)) continue;
 
     try {
@@ -1456,10 +1501,10 @@ export function generateSkillIndex(): number {
 
 /** Count skill subdirectories in ~/.pal/skills/ */
 export function countSkills(): number {
-  if (!existsSync(PAL_SKILLS_DIR)) return 0;
+  if (!existsSync(palSkillsDir())) return 0;
   try {
-    return readdirSync(PAL_SKILLS_DIR).filter((f) =>
-      existsSync(resolve(PAL_SKILLS_DIR, f, "SKILL.md"))
+    return readdirSync(palSkillsDir()).filter((f) =>
+      existsSync(resolve(palSkillsDir(), f, "SKILL.md"))
     ).length;
   } catch {
     return 0;

package/src/tools/agent/algorithm-reflect.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+
 /**
  * AlgorithmReflect — Append structured algorithm reflections to JSONL.
  *
@@ -14,6 +15,8 @@
 
 import { appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
+import { encodeAnchor } from "../../hooks/lib/anchor";
+import { loadMachine } from "../../hooks/lib/machine";
 import { paths } from "../../hooks/lib/paths";
 import { emit } from "../lib/emit";
 
@@ -22,6 +25,7 @@ import { emit } from "../lib/emit";
 interface AlgorithmReflection {
   timestamp: string;
   cwd: string;
+  m: string;
   task: string;
   criteria_count: number;
   criteria_passed: number;
@@ -41,6 +45,40 @@ function reflectionsPath(): string {
   return paths.reflectionsFile();
 }
 
+/**
+ * Assemble a reflection record from CLI-style input, stamping the current
+ * cwd (anchored) and this machine's id. Exported so the stamping logic is
+ * directly testable without going through argv parsing.
+ */
+export function buildReflection(input: {
+  task: string;
+  q1: string;
+  q2: string;
+  q3: string;
+  criteria_count?: number;
+  criteria_passed?: number;
+  criteria_failed?: number;
+  sentiment?: number;
+  scope?: string;
+}): AlgorithmReflection {
+  return {
+    timestamp: new Date().toISOString(),
+    cwd: encodeAnchor(process.cwd()),
+    m: loadMachine().id,
+    task: input.task,
+    criteria_count: input.criteria_count ?? 0,
+    criteria_passed: input.criteria_passed ?? 0,
+    criteria_failed: input.criteria_failed ?? 0,
+    sentiment: Math.max(1, Math.min(10, input.sentiment ?? 5)),
+    q1: input.q1,
+    q2: input.q2,
+    q3: input.q3,
+    // Default to general (the ~94% case); only "task-specific" suppresses it
+    // from algorithm-update clustering.
+    scope: input.scope === "task-specific" ? "task-specific" : "general",
+  };
+}
+
 function appendReflection(reflection: AlgorithmReflection): {
   success: boolean;
   message: string;
@@ -105,21 +143,17 @@ Output: algorithm-reflections.jsonl in memory/learning/reflections/
     process.exit(1);
   }
 
-  const reflection: AlgorithmReflection = {
-    timestamp: new Date().toISOString(),
-    cwd: process.cwd(),
+  const reflection = buildReflection({
     task: values.task,
-    criteria_count: parseInt(values.criteria || "0", 10),
-    criteria_passed: parseInt(values.passed || "0", 10),
-    criteria_failed: parseInt(values.failed || "0", 10),
-    sentiment: Math.max(1, Math.min(10, parseInt(values.sentiment || "5", 10))),
     q1: values.q1,
     q2: values.q2,
     q3: values.q3,
-    // Default to general (the ~94% case); only "task-specific" suppresses it
-    // from algorithm-update clustering.
-    scope: values.scope === "task-specific" ? "task-specific" : "general",
-  };
+    criteria_count: parseInt(values.criteria || "0", 10),
+    criteria_passed: parseInt(values.passed || "0", 10),
+    criteria_failed: parseInt(values.failed || "0", 10),
+    sentiment: parseInt(values.sentiment || "5", 10),
+    scope: values.scope,
+  });
 
   const result = appendReflection(reflection);
   emit.ok(result.message);