portable-agent-layer 0.66.1 → 0.67.0

package/assets/templates/settings.claude.json

@@ -132,6 +132,48 @@
             "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/RtkWrap.ts"
           }
         ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerSnapshot.ts"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerCommit.ts"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts"
+          }
+        ]
+      }
+    ],
+    "PermissionDenied": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PAL_AGENT=claude bun run {{PKG_ROOT}}/src/hooks/LedgerUnapplied.ts"
+          }
+        ]
       }
     ],
     "Stop": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.66.1",
+  "version": "0.67.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -42,7 +42,7 @@
     "lint": "biome lint",
     "lint-write": "biome lint --write",
     "check": "biome check",
-    "check-write": "biome check --write",
+    "check-write": "bun .agents/scripts/check-write.ts",
     "knip": "knip-bun",
     "klint": "klint",
     "jscpd": "jscpd --noTips",
@@ -96,6 +96,7 @@
   "dependencies": {
     "@clack/prompts": "^1.4.0",
     "adm-zip": "^0.5.17",
+    "fast-myers-diff": "^3.2.0",
     "marked": "18.0.4",
     "pdf-lib": "1.17.1",
     "playwright": "^1.60.0",

package/src/hooks/LedgerCommit.ts

@@ -0,0 +1,43 @@
+/**
+ * Hook: PostToolUse — pairs the parked before-state with the result and writes
+ * the ledger entry.
+ *
+ * Only a call that actually landed reaches this event, so every entry written
+ * here is an applied one. A denied or failed call fires the snapshot half and
+ * never this one, leaving its snapshot unclaimed — which is why claiming also
+ * reaps the ones that were abandoned.
+ *
+ * Silent and fail-open, for the same reason as its other half.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { claimPending, reapStalePending, recordAction } from "./lib/ledger";
+import { ledgeredCall } from "./lib/ledger-hook";
+import { logDebug } from "./lib/log";
+import { readStdinJSON } from "./lib/stdin";
+
+try {
+  const input = await readStdinJSON<Record<string, unknown>>();
+  if (!input) process.exit(0);
+
+  const call = ledgeredCall(input);
+  if (!call) process.exit(0);
+
+  // No snapshot means no before-state, and an entry claiming one it never had
+  // would be worse than the missing entry.
+  const pending = claimPending(call.toolUseId);
+  if (!pending) process.exit(0);
+
+  const entry = recordAction({
+    tool: pending.tool,
+    target: pending.target,
+    outcome: "applied",
+    before: pending.before,
+    after: existsSync(call.target) ? readFileSync(call.target, "utf-8") : null,
+  });
+
+  reapStalePending();
+  logDebug("LedgerCommit", `recorded ${entry.id} ${entry.tool} ${entry.target}`);
+} catch {
+  process.exit(0);
+}

package/src/hooks/LedgerSnapshot.ts

@@ -0,0 +1,37 @@
+/**
+ * Hook: PreToolUse — parks the target file's current contents before an edit.
+ *
+ * This half exists because the other half cannot do its job alone. A post-tool
+ * event fires once the file has already been rewritten, so the prior contents
+ * are gone and "what changed" is unanswerable from it. Reading the file here,
+ * before the tool runs, is the only moment the before-state still exists.
+ *
+ * Silent and fail-open: stdout is the agent's protocol channel, and a ledger
+ * that could block an edit would be a worse thing than a ledger with a gap.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { savePending } from "./lib/ledger";
+import { ledgeredCall } from "./lib/ledger-hook";
+import { logDebug } from "./lib/log";
+import { readStdinJSON } from "./lib/stdin";
+
+try {
+  const input = await readStdinJSON<Record<string, unknown>>();
+  if (!input) process.exit(0);
+
+  const call = ledgeredCall(input);
+  if (!call) process.exit(0);
+
+  savePending({
+    ...call,
+    // Absent rather than empty: a file that does not exist yet is a creation,
+    // which is a different event from a write over an empty file.
+    before: existsSync(call.target) ? readFileSync(call.target, "utf-8") : null,
+    ts: new Date().toISOString(),
+  });
+
+  logDebug("LedgerSnapshot", `captured ${call.tool} ${call.toolUseId}`);
+} catch {
+  process.exit(0);
+}

package/src/hooks/LedgerUnapplied.ts

@@ -0,0 +1,67 @@
+/**
+ * Hook: PostToolUseFailure and PermissionDenied — records an edit that was
+ * attempted and did not land.
+ *
+ * A log that keeps only what succeeded cannot answer what was attempted, and
+ * that is usually the question being asked of it. So the two endings that are
+ * not success are recorded too, and kept apart: `failed` is the tool's own
+ * attempt breaking, `denied` is something refusing to let it run.
+ *
+ * One hook serves both events because they differ only in which key carries the
+ * reason — a difference `unappliedVerdictOf` owns, so registering this on a
+ * third such event later is a line in that table rather than a new file.
+ *
+ * Not everything that fails to land reaches here. A manual denial at the
+ * permission dialog, a `deny` rule, and a PreToolUse hook's own block all fire
+ * PreToolUse and nothing after it; a schema rejection fires no hook at all.
+ * Those attempts leave a snapshot no half ever claims, which is what the reaper
+ * in ledger.ts is for.
+ *
+ * Silent and fail-open, for the same reason as the other halves.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import {
+  claimPending,
+  type PendingSnapshot,
+  reapStalePending,
+  recordAction,
+} from "./lib/ledger";
+import { ledgeredCall, unappliedVerdictOf } from "./lib/ledger-hook";
+import { logDebug } from "./lib/log";
+import { readStdinJSON } from "./lib/stdin";
+
+/**
+ * The snapshot is the trustworthy source, but its absence is recoverable here
+ * in a way it never is after a successful edit: nothing landed, so whatever is
+ * on disk now is still the before-state.
+ */
+function beforeState(pending: PendingSnapshot | null, target: string): string | null {
+  if (pending) return pending.before;
+  return existsSync(target) ? readFileSync(target, "utf-8") : null;
+}
+
+try {
+  const input = await readStdinJSON<Record<string, unknown>>();
+  if (!input) process.exit(0);
+
+  const call = ledgeredCall(input);
+  const verdict = call && unappliedVerdictOf(input);
+  if (!call || !verdict) process.exit(0);
+
+  const entry = recordAction({
+    tool: call.tool,
+    target: call.target,
+    outcome: verdict.outcome,
+    before: beforeState(claimPending(call.toolUseId), call.target),
+    // Nothing landed. That is what this event means, and it is the difference
+    // between this entry and an applied one.
+    after: null,
+    reason: verdict.reason,
+  });
+
+  reapStalePending();
+  logDebug("LedgerUnapplied", `recorded ${entry.id} ${entry.outcome} ${entry.target}`);
+} catch {
+  process.exit(0);
+}

package/src/hooks/lib/ledger-hook.ts

@@ -0,0 +1,107 @@
+/**
+ * What the two ledger hooks agree on: which tool calls are worth recording, and
+ * how to find the file and the call id in an agent's payload.
+ *
+ * Both halves must answer these identically — a pre-tool half that snapshots a
+ * tool the post-tool half ignores leaves a snapshot nothing ever claims.
+ */
+
+import { normalizeToolUse } from "./agent";
+import type { LedgerOutcome } from "./ledger";
+
+/**
+ * Edits and writes, which carry their own target in the call. A shell command's
+ * effect is not derivable from its arguments, so recording one honestly needs a
+ * different mechanism than reading the path out of the payload.
+ *
+ * Reads and searches are excluded because they are queries, not actions, and a
+ * ledger that logs them buries the changes among them.
+ */
+const LEDGERED_TOOLS = new Set(["edit", "write"]);
+
+/** Agents disagree on the spelling; the value is the same file either way. */
+const TARGET_KEYS = ["file_path", "filePath", "path"];
+
+export interface LedgeredCall {
+  toolUseId: string;
+  tool: string;
+  target: string;
+}
+
+/**
+ * The one reading of a payload both halves share. Asking the same question in
+ * two places is how they drift apart, and a drift here is silent: the pre-tool
+ * half parks a snapshot the post-tool half never comes to claim.
+ */
+export function ledgeredCall(payload: Record<string, unknown>): LedgeredCall | null {
+  const toolUse = normalizeToolUse(payload);
+  const toolUseId = toolUseIdOf(payload);
+  if (!toolUse || !toolUseId) return null;
+
+  const target = ledgeredTarget(toolUse.toolName, toolUse.toolInput);
+  return target ? { toolUseId, tool: toolUse.toolName, target } : null;
+}
+
+/**
+ * How a call that did not land reports itself. Two events, because the runtime
+ * treats the two endings as different things and so does the ledger: a tool
+ * that ran and errored is not a call something refused to run.
+ *
+ * They carry the same fact under different keys, which is the whole reason this
+ * mapping is written down in one place rather than read twice.
+ */
+const UNAPPLIED_EVENTS: Record<string, { outcome: LedgerOutcome; reasonKey: string }> = {
+  PostToolUseFailure: { outcome: "failed", reasonKey: "error" },
+  PermissionDenied: { outcome: "denied", reasonKey: "reason" },
+};
+
+export interface UnappliedVerdict {
+  outcome: LedgerOutcome;
+  reason?: string;
+}
+
+/**
+ * What became of a call, for the events that mean it did not land — or nothing
+ * when the payload is some other event, so one hook can be registered on both
+ * without having to be told which one it is being run for.
+ */
+export function unappliedVerdictOf(
+  payload: Record<string, unknown>
+): UnappliedVerdict | null {
+  const event = payload.hook_event_name ?? payload.hookEventName;
+  if (typeof event !== "string") return null;
+
+  const mapping = UNAPPLIED_EVENTS[event];
+  if (!mapping) return null;
+
+  const reason = payload[mapping.reasonKey];
+  // A reason the runtime did not send is left absent rather than invented: an
+  // entry that states a cause it does not have is worse than one that admits none.
+  return typeof reason === "string" && reason.length > 0
+    ? { outcome: mapping.outcome, reason }
+    : { outcome: mapping.outcome };
+}
+
+export function toolUseIdOf(payload: Record<string, unknown>): string | null {
+  for (const key of ["tool_use_id", "toolUseId", "tool_call_id"]) {
+    const value = payload[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return null;
+}
+
+/**
+ * The absolute path this call will change, or nothing if the call is not one
+ * the ledger records.
+ */
+export function ledgeredTarget(
+  toolName: string,
+  toolInput: Record<string, unknown>
+): string | null {
+  if (!LEDGERED_TOOLS.has(toolName.toLowerCase())) return null;
+  for (const key of TARGET_KEYS) {
+    const value = toolInput[key];
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return null;
+}

package/src/hooks/lib/ledger.ts

@@ -0,0 +1,328 @@
+/**
+ * Action ledger — an append-only record of what an agent changed, and under
+ * whose authority.
+ *
+ * A transcript says a tool was called. It does not say what the file looked
+ * like before, so it cannot answer "what changed" after the fact — the prior
+ * contents are gone by the time anything downstream reads it. The ledger is
+ * therefore written at the moment of the change, from both sides of it.
+ *
+ * Scope is deliberately narrow: edits and writes, which carry their own
+ * before/after in the call. A shell command's effect is not derivable from its
+ * arguments, so recording one honestly would need a different mechanism than
+ * this file — see the AGENTS.md rule steering file changes onto the edit tools.
+ *
+ * Reads and searches are excluded on purpose. They are queries, not actions,
+ * and a ledger that logs them buries the changes among them.
+ *
+ * This module is silent. It runs inside hooks, where stdout is the agent's
+ * protocol channel, so it returns what it wrote and leaves reporting to the
+ * caller.
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+import { calcPatch } from "fast-myers-diff";
+import { currentAttribution, type RecordAttribution } from "./actor";
+import { encodeAnchor } from "./anchor";
+import { ensureDir, paths } from "./paths";
+
+/**
+ * What became of the action.
+ *
+ * `failed` and `denied` are kept apart because they answer different questions.
+ * A failure is the agent's own attempt not working — a bad path, a stale match,
+ * a permission on disk. A denial is a human refusing it. Collapsing them would
+ * lose the only signal in the record that says where the boundary was drawn,
+ * and "what did I try that was refused" is a question worth being able to ask
+ * separately from "what did I try that broke".
+ */
+export type LedgerOutcome = "applied" | "failed" | "denied";
+
+/**
+ * One side of a change, identified rather than reproduced. The hash ties the
+ * entry to a real file — apply the delta to something matching `before.hash`
+ * and you must land on `after.hash` — and the byte count says how big that file
+ * was without keeping it.
+ */
+export interface LedgerState {
+  hash: string;
+  bytes: number;
+}
+
+/**
+ * One contiguous replacement. `at` and `remove` index the before-state and are
+ * not shifted by earlier hunks in the same delta, which is what the diff
+ * produces and what applying them in order with a running offset expects.
+ */
+export interface LedgerHunk {
+  at: number;
+  remove: number;
+  insert: string[];
+}
+
+/**
+ * What changed, at line granularity.
+ *
+ * Storing this rather than both whole files is what lets the record scale with
+ * the size of the change instead of the size of the file. Under the old shape a
+ * four-line edit to a large file kept two hashes and nothing else, so the
+ * entries that said least were the ones about the biggest files.
+ */
+export interface LedgerDelta {
+  hunks: LedgerHunk[];
+  /** Set when the change itself was too large to keep. Its absence means the hunks are complete. */
+  truncated?: boolean;
+}
+
+export interface LedgerEntry extends RecordAttribution {
+  id: string;
+  ts: string;
+  /** The tool that made the change — Edit or Write today. */
+  tool: string;
+  /** Project-anchored path, so the entry survives a different mount or machine. */
+  target: string;
+  outcome: LedgerOutcome;
+  /** Null when nothing was there before: a file creation has no prior state. */
+  before: LedgerState | null;
+  /** Null when nothing landed, which is what a failed or denied action means. */
+  after: LedgerState | null;
+  /**
+   * The change from one side to the other. Absent when nothing landed: an
+   * action that was refused did not empty the file, and a delta saying it did
+   * would be the ledger stating something that never happened.
+   */
+  delta?: LedgerDelta;
+  /** Why the action did not land. Absent on an applied one. */
+  reason?: string;
+}
+
+export interface RecordActionInput {
+  tool: string;
+  /** Absolute path of the file the action targeted. */
+  target: string;
+  outcome: LedgerOutcome;
+  /** Prior content; null for a file creation. */
+  before: string | null;
+  /** Resulting content; null when nothing landed. */
+  after: string | null;
+  reason?: string;
+}
+
+/**
+ * A change larger than this is recorded as having happened without being kept.
+ * It caps the delta rather than the files, so what fits is decided by how much
+ * an action changed, not by how big the thing it changed happened to be.
+ */
+const MAX_DELTA_BYTES = 4096;
+
+/** Size at which the active file is rotated aside. */
+const MAX_LEDGER_BYTES = 4 * 1024 * 1024;
+
+const ACTIVE = "actions.jsonl";
+
+export function ledgerPath(): string {
+  return resolve(paths.ledger(), ACTIVE);
+}
+
+function hash(content: string): string {
+  return new Bun.CryptoHasher("sha256").update(content, "utf-8").digest("hex");
+}
+
+function stateOf(content: string | null): LedgerState | null {
+  if (content === null) return null;
+  return { hash: hash(content), bytes: Buffer.byteLength(content, "utf-8") };
+}
+
+/**
+ * Splitting on newlines keeps the trailing one: "a\n" becomes ["a", ""], and
+ * joining puts it back. A file and its line list round-trip exactly, which is
+ * what makes a reconstructed after-state hash-identical to the real one.
+ */
+function toLines(content: string | null): string[] {
+  return content === null ? [] : content.split("\n");
+}
+
+/**
+ * The change between two states, or nothing when there was no transition to
+ * describe. An action that did not land has no delta — see LedgerEntry.delta.
+ */
+function deltaOf(before: string | null, after: string | null): LedgerDelta | undefined {
+  if (after === null) return undefined;
+
+  const hunks: LedgerHunk[] = [];
+  for (const [at, end, insert] of calcPatch(toLines(before), toLines(after))) {
+    hunks.push({ at, remove: end - at, insert: [...insert] });
+  }
+  if (hunks.length === 0) return undefined;
+
+  const delta: LedgerDelta = { hunks };
+  return Buffer.byteLength(JSON.stringify(delta), "utf-8") > MAX_DELTA_BYTES
+    ? { hunks: [], truncated: true }
+    : delta;
+}
+
+/**
+ * Rebuild the after-state from the before-state and the delta, or nothing when
+ * the delta was too large to keep.
+ *
+ * This is what makes an entry checkable rather than merely plausible: the hash
+ * of what this returns must equal the entry's `after.hash`. It is also the read
+ * side of the ledger — a stored change is only evidence if it can be replayed.
+ */
+export function applyDelta(before: string | null, delta: LedgerDelta): string | null {
+  if (delta.truncated) return null;
+
+  const lines = toLines(before);
+  const out: string[] = [];
+  let cursor = 0;
+  for (const hunk of delta.hunks) {
+    out.push(...lines.slice(cursor, hunk.at), ...hunk.insert);
+    cursor = hunk.at + hunk.remove;
+  }
+  out.push(...lines.slice(cursor));
+  return out.join("\n");
+}
+
+function generateId(): string {
+  return Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
+}
+
+/**
+ * Move the active file aside once it crosses the size cap, so reads stay cheap
+ * without discarding anything. A count-based trim would delete the oldest
+ * entries first, which in an audit record is the evidence most worth keeping.
+ */
+function rotateIfFull(file: string): void {
+  if (!existsSync(file) || statSync(file).size < MAX_LEDGER_BYTES) return;
+  renameSync(file, freeArchivePath(new Date().toISOString().replace(/[:.]/g, "-")));
+}
+
+/**
+ * A name no archive already holds. Two rotations within the same millisecond
+ * agree on a stamp, and renaming onto a taken name destroys that archive
+ * without a trace — the one failure mode an append-only record cannot have.
+ */
+function freeArchivePath(stamp: string): string {
+  const nth = (n: number) => {
+    const suffix = n ? `-${n}` : "";
+    return resolve(paths.ledger(), `actions-${stamp}${suffix}.jsonl`);
+  };
+  let n = 0;
+  while (existsSync(nth(n))) n++;
+  return nth(n);
+}
+
+/**
+ * Append one action to the ledger and return the entry as written.
+ *
+ * An action that did not land is recorded like any other: a log that keeps only
+ * what succeeded cannot answer what was attempted, which is usually the question
+ * being asked of it.
+ */
+export function recordAction(input: RecordActionInput): LedgerEntry {
+  const delta = deltaOf(input.before, input.after);
+  const entry: LedgerEntry = {
+    id: generateId(),
+    ts: new Date().toISOString(),
+    ...currentAttribution(),
+    tool: input.tool,
+    target: encodeAnchor(input.target),
+    outcome: input.outcome,
+    before: stateOf(input.before),
+    after: stateOf(input.after),
+    ...(delta ? { delta } : {}),
+    ...(input.reason ? { reason: input.reason } : {}),
+  };
+
+  const file = ledgerPath();
+  rotateIfFull(file);
+  appendFileSync(file, `${JSON.stringify(entry)}\n`, "utf-8");
+  return entry;
+}
+
+/**
+ * The before-state, held between the two halves of one tool call.
+ *
+ * A post-tool event alone cannot produce it: by the time the tool has run, the
+ * prior contents are gone. So the pre-tool half reads the file and parks it
+ * here, and the post-tool half claims it back and pairs it with the result.
+ */
+export interface PendingSnapshot {
+  toolUseId: string;
+  tool: string;
+  target: string;
+  before: string | null;
+  ts: string;
+}
+
+/** How long a snapshot waits for a second half that may never come. */
+const PENDING_TTL_MS = 60 * 60 * 1000;
+
+function pendingDir(): string {
+  return ensureDir(resolve(paths.ledger(), "pending"));
+}
+
+/**
+ * A tool-call id is an identifier from another system, and it lands here as a
+ * filename — so it is reduced to characters that cannot climb out of the
+ * directory rather than trusted to be well-formed.
+ */
+function pendingPath(toolUseId: string): string {
+  return resolve(pendingDir(), `${toolUseId.replace(/[^A-Za-z0-9_-]/g, "")}.json`);
+}
+
+export function savePending(snapshot: PendingSnapshot): void {
+  writeFileSync(pendingPath(snapshot.toolUseId), JSON.stringify(snapshot), "utf-8");
+}
+
+/**
+ * Take the snapshot for this tool call, removing it in the same step. Claiming
+ * is one-shot on purpose: a snapshot that stayed put after being read could be
+ * paired with a second result and record a change that never happened.
+ */
+export function claimPending(toolUseId: string): PendingSnapshot | null {
+  const file = pendingPath(toolUseId);
+  if (!existsSync(file)) return null;
+  try {
+    const snapshot = JSON.parse(readFileSync(file, "utf-8")) as PendingSnapshot;
+    unlinkSync(file);
+    return snapshot;
+  } catch {
+    unlinkSync(file);
+    return null;
+  }
+}
+
+/**
+ * Drop snapshots nothing ever claimed.
+ *
+ * Applying, failing and being denied by auto mode all fire a second half that
+ * claims the snapshot. What is left here is the endings that fire nothing after
+ * the pre-tool half — a manual denial at the permission dialog, a deny rule, a
+ * pre-tool hook's own block — plus anything interrupted mid-call.
+ *
+ * They are dropped rather than recorded because the ledger would have to invent
+ * which of those it was. The attempt is real and currently goes unrecorded; see
+ * the manual-denial gap in the project's ISCs.
+ */
+export function reapStalePending(now: number = Date.now()): number {
+  const dir = pendingDir();
+  let reaped = 0;
+  for (const name of readdirSync(dir)) {
+    const file = resolve(dir, name);
+    if (now - statSync(file).mtimeMs < PENDING_TTL_MS) continue;
+    unlinkSync(file);
+    reaped++;
+  }
+  return reaped;
+}

package/src/hooks/lib/paths.ts

@@ -54,6 +54,7 @@ export const paths = {
   reflectionsFile: () =>
     home("memory", "learning", "reflections", "algorithm-reflections.jsonl"),
   retrievalIndex: () => home("memory", "learning", ".retrieval-index.json"),
+  ledger: () => ensureDir(home("memory", "ledger")),
   progress: () => ensureDir(home("memory", "state", "progress")),
   projectHistory: () => ensureDir(home("memory", "projects")),
   sessionLearning: () => ensureDir(home("memory", "learning", "session")),

package/src/targets/lib.ts

@@ -23,11 +23,27 @@ import { declaredTriggers } from "../hooks/lib/skill-triggers";
 
 // --- Colored logging ---
 
+function runningUnderTest(): boolean {
+  return process.env.PAL_TEST_SANDBOX === "1";
+}
+
 export const log = {
   info: (msg: string) => console.log(`\x1b[34m[pal]\x1b[0m ${msg}`),
   success: (msg: string) => console.log(`\x1b[32m[pal]\x1b[0m ${msg}`),
   warn: (msg: string) => console.log(`\x1b[33m[pal]\x1b[0m ${msg}`),
   error: (msg: string) => console.error(`\x1b[31m[pal]\x1b[0m ${msg}`),
+
+  /**
+   * Per-item narration from inside a loop, where the caller already reports the
+   * total. Silent under the test runner: the suite drives these installers by
+   * the hundred against temp directories, so the lines name files that were
+   * never on this machine — and they are the only output no caller asserts on,
+   * precisely because the summary is what carries the result.
+   */
+  detail: (msg: string) => {
+    if (runningUnderTest()) return;
+    console.log(`\x1b[34m[pal]\x1b[0m ${msg}`);
+  },
 };
 
 // --- JSON helpers ---
@@ -784,7 +800,7 @@ export function copySkills(claudeSkillsDir: string): number {
   let count = 0;
 
   for (const name of pruneStaleSkillLinks(claudeSkillsDir)) {
-    log.info(`Removed stale skill link: ${name}`);
+    log.detail(`Removed stale skill link: ${name}`);
   }
 
   for (const name of readdirSync(skillsDir)) {
@@ -994,7 +1010,7 @@ export function removeSkills(claudeSkillsDir: string): string[] {
       }
     }
     removed.push(name);
-    log.info(`Removed skill: ${name}`);
+    log.detail(`Removed skill: ${name}`);
   }
 
   // Remove ~/.agents/skills/ → ~/.pal/skills/ symlink
@@ -1031,7 +1047,7 @@ export function removeAgents(): string[] {
       unlinkSync(dst);
       const name = file.replace(/\.md$/, "");
       removed.push(name);
-      log.info(`Removed agent: ${name}`);
+      log.detail(`Removed agent: ${name}`);
     }
   }
   return removed;
@@ -1141,7 +1157,7 @@ function uninstallAgents(targetDir: string, label: string): string[] {
     if (existsSync(dst)) {
       unlinkSync(dst);
       removed.push(file.replace(/\.md$/, ""));
-      log.info(`Removed ${label} agent: ${file.replace(/\.md$/, "")}`);
+      log.detail(`Removed ${label} agent: ${file.replace(/\.md$/, "")}`);
     }
   }
   return removed;