portable-agent-layer 0.68.0 → 0.69.0

package/README.md

@@ -88,6 +88,7 @@ pal cli status        # check your setup
 | `pal cli actor [label <name>]` | Show or rename the actor — who caused a record. Travels with an export, so a shared memory can tell two people apart |
 | `pal cli machine [label <name>]` | Show or rename this install — where a record was written. Never leaves the machine |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
+| `pal cli ledger` | Query the action ledger — `log`, `show <id>`, `stats`, filtered by `--project`, `--since`, `--actor`, `--machine`, `--runtime`, `--outcome`, `--tool`, `--target` |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
 | `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
 | `pal cli subagent link <name>` | Install a personal `~/.pal/agents/<name>.md` (merged multi-platform definition) into every installed agent, split per platform |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -16,6 +16,7 @@
  *   status                            Show current PAL configuration
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
+ *   ledger <sub> [filters]            Query the action ledger (log · show · stats)
  *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
  *   skill doctor <name|--all>         Evaluate one skill, or every installed skill, against the authoring best practices
  *   subagent link <name>             Install a personal ~/.pal/agents/<name>.md into installed agents
@@ -232,6 +233,12 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "ledger": {
+      const { runLedger } = await import("./ledger");
+      const code = await runLedger(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "subagent": {
       const { runSubagent } = await import("./subagent");
       const code = await runSubagent(args);
@@ -299,6 +306,8 @@ function showHelp() {
     pal cli machine [label <name>]          Show or rename this install (where it was written)
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)
+    pal cli ledger <sub> [filters]          Query the action ledger (log · show · stats)
+                                            e.g. ledger log --project X --since 7d
     pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
     pal cli skill doctor <name|--all>       Evaluate one skill, or every installed skill
     pal cli skill author-model              Print the flagship model that authors skills for the active agent

package/src/cli/ledger.ts

@@ -0,0 +1,329 @@
+/**
+ * pal cli ledger — query the action ledger.
+ *
+ * Thin presentation layer over src/tools/ledger/query.ts. Owns formatting and
+ * argv parsing only; every question about the records themselves is answered
+ * there.
+ *
+ * Subcommands:
+ *   log [filters]     Matching actions, oldest first
+ *   show <id>         One action in full, with its change and current standing
+ *   stats [filters]   Counts by outcome, runtime, actor, tool and target
+ */
+
+import { parseArgs } from "node:util";
+import type { LedgerEntry } from "../hooks/lib/ledger";
+import {
+  type ChainVerdict,
+  chainVerdict,
+  changeShape,
+  findEntry,
+  type LedgerFilter,
+  ledgerFiles,
+  locate,
+  parseSince,
+  queryLedger,
+  type Standing,
+  standing,
+  summarize,
+} from "../tools/ledger/query";
+
+const FILTER_OPTIONS = {
+  project: { type: "string" },
+  since: { type: "string" },
+  until: { type: "string" },
+  actor: { type: "string" },
+  machine: { type: "string" },
+  runtime: { type: "string" },
+  outcome: { type: "string" },
+  tool: { type: "string" },
+  target: { type: "string" },
+  limit: { type: "string" },
+  json: { type: "boolean" },
+} as const;
+
+export async function runLedger(args: string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  switch (sub) {
+    case "log":
+      return cmdLog(rest);
+    case "show":
+      return cmdShow(rest);
+    case "stats":
+      return cmdStats(rest);
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      showHelp();
+      return 0;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      showHelp();
+      return 1;
+  }
+}
+
+function showHelp(): void {
+  console.log(`
+  Usage:
+    pal cli ledger <subcommand> [filters]
+
+  Subcommands:
+    log [filters]              Matching actions, oldest first
+    show <id>                  One action in full: change, target, standing
+    stats [filters]            Counts by outcome, runtime, actor, tool, target
+
+  Filters:
+    --project <slug>           Actions against a registered project
+    --since <7d|2026-09-01>    A duration back from now, or a date
+    --until <date>             Upper bound on the timestamp
+    --actor <id>               Who caused it
+    --machine <id>             Which install wrote it
+    --runtime <agent>          claude, cursor, codex, copilot, opencode
+    --outcome <applied|failed|denied>
+    --tool <Edit|Write>
+    --target <substring>       Match anywhere in the recorded path
+    --limit <n>                Keep the newest n matches
+    --json                     Machine-readable output
+
+  Examples:
+    pal cli ledger log --project portable-agent-layer --since 7d
+    pal cli ledger log --target memory/ --outcome applied
+    pal cli ledger stats --since 24h
+`);
+}
+
+/** A filter that silently ignored an unparseable window would answer the wrong question. */
+function buildFilter(values: Record<string, unknown>): LedgerFilter | string {
+  const filter: LedgerFilter = {};
+  for (const key of [
+    "project",
+    "actor",
+    "machine",
+    "runtime",
+    "outcome",
+    "tool",
+    "target",
+  ] as const) {
+    const value = values[key];
+    if (typeof value === "string") filter[key] = value;
+  }
+
+  for (const key of ["since", "until"] as const) {
+    const spec = values[key];
+    if (typeof spec !== "string") continue;
+    const at = parseSince(spec);
+    if (!at) return `Unrecognised --${key}: ${spec} (use 7d, 24h, or a date)`;
+    filter[key] = at;
+  }
+
+  if (typeof values.limit === "string") {
+    const limit = Number(values.limit);
+    if (!Number.isInteger(limit) || limit < 1)
+      return `--limit must be a positive integer`;
+    filter.limit = limit;
+  }
+  return filter;
+}
+
+function parseFilters(args: string[]): { filter: LedgerFilter; json: boolean } | string {
+  try {
+    const { values } = parseArgs({
+      args,
+      options: FILTER_OPTIONS,
+      allowPositionals: true,
+    });
+    const filter = buildFilter(values);
+    return typeof filter === "string" ? filter : { filter, json: values.json === true };
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+function shortId(id: string): string {
+  return id.slice(0, 11).padEnd(11);
+}
+
+function changedLines(entry: LedgerEntry): string {
+  const shape = changeShape(entry);
+  switch (shape.kind) {
+    case "redacted":
+      return "withheld";
+    case "truncated":
+      return "too large";
+    case "none":
+      return "no change";
+    default: {
+      const added = shape.delta.hunks.reduce((n, h) => n + h.insert.length, 0);
+      const removed = shape.delta.hunks.reduce((n, h) => n + h.remove, 0);
+      return `+${added} -${removed}`;
+    }
+  }
+}
+
+function cmdLog(args: string[]): number {
+  const parsed = parseFilters(args);
+  if (typeof parsed === "string") return fail(parsed);
+
+  const entries = queryLedger(parsed.filter);
+  if (parsed.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return 0;
+  }
+
+  if (entries.length === 0) {
+    console.log("No actions match.");
+    return 0;
+  }
+
+  for (const entry of entries) {
+    console.log(
+      `${entry.ts}  ${shortId(entry.id)}  ${entry.outcome.padEnd(7)}  ${entry.runtime.padEnd(8)}  ${entry.tool.padEnd(5)}  ${changedLines(entry).padEnd(9)}  ${entry.target}`
+    );
+  }
+  console.log(
+    `\n${entries.length} action(s) across ${ledgerFiles().length} ledger file(s).`
+  );
+  return 0;
+}
+
+function describeStanding(verdict: Standing): string {
+  switch (verdict.state) {
+    case "in-place":
+      return "still in place on disk";
+    case "reverted":
+      return verdict.replays
+        ? "reverted since — the stored change replays cleanly onto the file as it stands"
+        : "reverted since, but the stored change no longer replays";
+    case "superseded":
+      return `superseded — the file has changed again since (now ${verdict.hash.slice(0, 12)})`;
+    case "missing":
+      return "the target no longer exists";
+    default:
+      return verdict.why;
+  }
+}
+
+function describeChain(verdict: ChainVerdict): string {
+  switch (verdict.state) {
+    case "latest":
+      return "the newest recorded action on this target";
+    case "undone":
+      return `undone by ${verdict.by} at ${verdict.at}, which put the file back as this one found it`;
+    default:
+      return `changed again by ${verdict.by} at ${verdict.at}`;
+  }
+}
+
+const UNKEPT_CHANGE: Record<string, string> = {
+  redacted: "contents withheld — the target is one the ledger never keeps",
+  truncated: "the change was too large to keep; its size and hashes remain",
+  none: "no change was recorded, which is what a refused action looks like",
+};
+
+function printChange(entry: LedgerEntry): void {
+  const shape = changeShape(entry);
+  if (shape.kind !== "hunks") {
+    console.log(`  ${UNKEPT_CHANGE[shape.kind]}`);
+    return;
+  }
+  for (const hunk of shape.delta.hunks) {
+    console.log(`  @@ line ${hunk.at + 1}, -${hunk.remove} +${hunk.insert.length}`);
+    for (const line of hunk.insert) console.log(`  + ${line}`);
+  }
+}
+
+function cmdShow(args: string[]): number {
+  const [id, ...rest] = args;
+  if (!id) return fail("Usage: pal cli ledger show <id>");
+
+  const entry = findEntry(id);
+  if (!entry) return fail(`No action with id ${id}`);
+
+  if (rest.includes("--json")) {
+    console.log(
+      JSON.stringify(
+        {
+          ...entry,
+          resolved: locate(entry),
+          standing: standing(entry),
+          chain: chainVerdict(entry),
+        },
+        null,
+        2
+      )
+    );
+    return 0;
+  }
+
+  console.log(`
+  ${entry.id}  ${entry.ts}
+  ${entry.tool} → ${outcomeLine(entry)}
+  target      ${entry.target}
+  on disk     ${diskLine(entry)}
+  runtime     ${entry.runtime}, authority ${entry.authority}
+  actor       ${entry.actor}
+  machine     ${entry.machine}
+  size        ${sizeOf(entry.before, "created")} → ${sizeOf(entry.after, "nothing landed")}
+  standing    ${describeStanding(standing(entry))}
+  in ledger   ${describeChain(chainVerdict(entry))}
+
+  change`);
+  printChange(entry);
+  return 0;
+}
+
+function outcomeLine(entry: LedgerEntry): string {
+  return entry.reason ? `${entry.outcome} (${entry.reason})` : entry.outcome;
+}
+
+function diskLine(entry: LedgerEntry): string {
+  const found = locate(entry);
+  if (found.path) return found.path;
+  return `unresolvable: project ${found.unresolvable} is not registered here`;
+}
+
+function sizeOf(state: LedgerEntry["before"], absent: string): string {
+  return state ? `${state.bytes}b` : absent;
+}
+
+function printTally(label: string, counts: Record<string, number>): void {
+  const rows = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+  if (rows.length === 0) return;
+  console.log(`  ${label}`);
+  for (const [key, count] of rows)
+    console.log(`    ${String(count).padStart(6)}  ${key}`);
+}
+
+function cmdStats(args: string[]): number {
+  const parsed = parseFilters(args);
+  if (typeof parsed === "string") return fail(parsed);
+
+  const stats = summarize(queryLedger(parsed.filter));
+  if (parsed.json) {
+    console.log(JSON.stringify(stats, null, 2));
+    return 0;
+  }
+
+  console.log(
+    `\n  ${stats.total} action(s) across ${ledgerFiles().length} ledger file(s)`
+  );
+  if (stats.span) console.log(`  ${stats.span.first} → ${stats.span.last}\n`);
+  printTally("outcome", stats.byOutcome);
+  printTally("runtime", stats.byRuntime);
+  printTally("tool", stats.byTool);
+  printTally("actor", stats.byActor);
+  if (stats.topTargets.length > 0) {
+    console.log("  most-changed targets");
+    for (const { target, count } of stats.topTargets) {
+      console.log(`    ${String(count).padStart(6)}  ${target}`);
+    }
+  }
+  return 0;
+}
+
+function fail(message: string): number {
+  console.error(message);
+  return 1;
+}

package/src/hooks/lib/agent.ts

@@ -6,9 +6,10 @@
  * one-shot subscription-backed inference. These helpers identify which agent
  * is currently running PAL so downstream code can dispatch accordingly.
  *
- * Primary signal: PAL_AGENT env var, set by every install template/plugin in
- * `assets/templates/*` and `src/targets/opencode/plugin.ts`. IDE-provided env
- * vars are used as secondary fallbacks for environments that forward them.
+ * Detection reads PAL_AGENT first (set in-process by
+ * `src/targets/opencode/plugin.ts`), then the host's own environment, and only
+ * then the `--agent=` flag the install templates in `assets/templates/*` put
+ * on the hook command line. See declaredAgent for why that order.
  */
 
 export type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode" | "vscode";
@@ -42,15 +43,70 @@ function agentFromArgv(): AgentType | undefined {
   return value && KNOWN_AGENTS.has(value as AgentType) ? (value as AgentType) : undefined;
 }
 
+/**
+ * cursor-agent's own session env. CURSOR_VERSION is kept because it costs
+ * nothing and appears on no other surface, but it is not the primary signal —
+ * it is absent from the session env that hook children inherit.
+ */
+function inCursorAgent(): boolean {
+  return Boolean(
+    process.env.CURSOR_AGENT ??
+      process.env.CURSOR_VERSION ??
+      (process.env.CURSOR_INVOKED_AS === "cursor-agent" || undefined)
+  );
+}
+
+function inCodex(): boolean {
+  return Boolean(process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX);
+}
+
+/**
+ * Set by every Claude Code host — cli, claude-vscode, claude-desktop — and by
+ * none of the others. The Cursor extension carries CURSOR_SPAWN_CHAIN and
+ * friends but no CURSOR_AGENT, so it lands here rather than on cursor.
+ */
+function inClaudeCode(): boolean {
+  return Boolean(process.env.CLAUDE_CODE_ENTRYPOINT);
+}
+
+/**
+ * Which host is running this process, read from what the host itself exported.
+ *
+ * cursor-agent is tested first on purpose: it emulates Claude Code closely
+ * enough to inject CLAUDE_PROJECT_DIR and CLAUDE_CODE_AUTO_COMPACT_WINDOW, so
+ * a CLAUDE_* variable is evidence of Claude Code only once Cursor is ruled out.
+ */
 function agentFromRuntimeEnv(): AgentType | undefined {
-  if (process.env.CURSOR_VERSION) return "cursor";
-  if (process.env.CODEX_CLI_VERSION ?? process.env.OPENAI_CODEX) return "codex";
+  if (inCursorAgent()) return "cursor";
+  if (inCodex()) return "codex";
+  if (inClaudeCode()) return "claude";
   return undefined;
 }
 
-/** The agent something actually said was running, or undefined if nothing did. */
+/**
+ * Cursor and VS Code both load ~/.claude/settings.json alongside their own
+ * config, so a `--agent=claude` flag names a file three hosts share and cannot
+ * by itself say which one is running. Every other flag comes from a config only
+ * its own agent reads.
+ */
+const SHARED_CONFIG_AGENTS: ReadonlySet<AgentType> = new Set(["claude", "vscode"]);
+
+/**
+ * The agent something actually said was running, or undefined if nothing did.
+ *
+ * Host evidence outranks the flag only for the shared config, because one
+ * cursor-agent edit runs both ~/.cursor/hooks.json and ~/.claude/settings.json
+ * and the winner of that race used to decide the recorded runtime. It must not
+ * outrank an unambiguous flag: a Copilot or Codex session started from a Claude
+ * Code terminal inherits CLAUDE_CODE_ENTRYPOINT, and ambient inheritance is
+ * weaker evidence than an agent's own registration.
+ */
 export function declaredAgent(): AgentType | undefined {
-  return agentFromArgv() ?? agentFromEnv() ?? agentFromRuntimeEnv();
+  const explicit = agentFromEnv();
+  if (explicit) return explicit;
+  const flag = agentFromArgv();
+  if (flag && !SHARED_CONFIG_AGENTS.has(flag)) return flag;
+  return agentFromRuntimeEnv() ?? flag;
 }
 
 /** Which agent's conventions to follow. Assumes "claude" when undeclared. */

package/src/tools/agent/project.ts

@@ -392,11 +392,36 @@ interface Isc {
   status: IscStatus;
 }
 
+/**
+ * An ISC is one markdown line, so a newline in its text would end the record
+ * and strand every paragraph after it as unparseable debris. Backslashes are
+ * escaped first so that decoding a literal "\n" in a regex cannot be mistaken
+ * for the separator.
+ */
+function encodeIscText(text: string): string {
+  return text
+    .replaceAll("\\", "\\\\")
+    .replaceAll("\r\n", "\n")
+    .replaceAll("\r", "\n")
+    .replaceAll("\n", "\\n");
+}
+
+const ISC_UNESCAPE: Record<string, string> = { n: "\n", "\\": "\\" };
+
+function decodeIscText(stored: string): string {
+  return stored.replaceAll(/\\(.)/g, (whole, ch) => ISC_UNESCAPE[ch] ?? whole);
+}
+
 function parseIscs(criteria: string): Isc[] {
   const out: Isc[] = [];
   for (const line of criteria.split("\n")) {
     const m = new RegExp(/^-\s+\[( |x|~)\]\s+ISC-(\d+):\s+(.+)$/i).exec(line);
-    if (m) out.push({ id: Number(m[2]), text: m[3].trim(), status: statusFromBox(m[1]) });
+    if (m)
+      out.push({
+        id: Number(m[2]),
+        text: decodeIscText(m[3].trim()),
+        status: statusFromBox(m[1]),
+      });
   }
   return out;
 }
@@ -471,7 +496,7 @@ function cmdAddIsc(args: string[]): void {
   const p = requireProject(name);
   const current = p.criteria ?? "";
   const id = nextIscId(p);
-  const newLine = `- [ ] ISC-${id}: ${title}`;
+  const newLine = `- [ ] ISC-${id}: ${encodeIscText(title)}`;
   p.criteria = current ? `${current.trimEnd()}\n${newLine}` : newLine;
   p.updated = now();
   writeProject(p);
@@ -628,7 +653,7 @@ function cmdEditIsc(args: string[]): void {
       .split("\n")
       .map((l) =>
         new RegExp(String.raw`^-\s+\[[ x~]\]\s+ISC-${id}:`, "i").test(l)
-          ? `- ${box} ISC-${id}: ${text}`
+          ? `- ${box} ISC-${id}: ${encodeIscText(text)}`
           : l
       )
       .join("\n");

package/src/tools/ledger/query.ts

@@ -0,0 +1,300 @@
+/**
+ * The read side of the action ledger — typed queries over what was recorded.
+ *
+ * The write side stores enough to answer questions, but only in the shape that
+ * was cheap to write: one JSON object per line, targets held as project
+ * anchors, changes held as line deltas. Reading it back with a grep gets the
+ * lines and loses the meaning — a slug is not a path, and a delta is not a
+ * diff until something replays it.
+ *
+ * Every query here spans the archives as well as the active file. Rotation
+ * exists so history survives; a reader that opened only the live file would
+ * quietly answer "what changed" with "what changed recently".
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { resolveAnchor } from "../../hooks/lib/anchor";
+import {
+  applyDelta,
+  type LedgerDelta,
+  type LedgerEntry,
+  ledgerPath,
+} from "../../hooks/lib/ledger";
+import { paths } from "../../hooks/lib/paths";
+
+const ARCHIVE_RE = /^actions-.*\.jsonl$/;
+
+const ANCHOR_SLUG_RE = /^\{proj:([a-z0-9_-]+)\}/;
+
+export interface LedgerFilter {
+  project?: string;
+  since?: Date;
+  until?: Date;
+  actor?: string;
+  machine?: string;
+  runtime?: string;
+  outcome?: string;
+  tool?: string;
+  target?: string;
+  limit?: number;
+}
+
+/**
+ * Archives first, then the active file, so the result reads oldest to newest
+ * the way the underlying appends do. Names carry an ISO stamp, which sorts
+ * lexicographically into chronological order.
+ */
+export function ledgerFiles(): string[] {
+  const dir = paths.ledger();
+  const archives = readdirSync(dir)
+    .filter((name) => ARCHIVE_RE.test(name))
+    .sort()
+    .map((name) => resolve(dir, name));
+  const active = ledgerPath();
+  return existsSync(active) ? [...archives, active] : archives;
+}
+
+function entriesInFile(file: string): LedgerEntry[] {
+  if (!existsSync(file)) return [];
+  const entries: LedgerEntry[] = [];
+  for (const line of readFileSync(file, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line) as LedgerEntry);
+    } catch {
+      /* a partially written line is not evidence; skip it */
+    }
+  }
+  return entries;
+}
+
+export function readLedger(): LedgerEntry[] {
+  return ledgerFiles().flatMap(entriesInFile);
+}
+
+export function anchorSlugOf(target: string): string | null {
+  return ANCHOR_SLUG_RE.exec(target)?.[1] ?? null;
+}
+
+/**
+ * An entry names its project two ways depending on when it was written, and a
+ * query has to accept both. An anchored target carries the slug outright. A
+ * plain one predates anchoring or fell outside every registered project, and
+ * only means this project if it resolves under its root on this machine.
+ */
+function inProject(entry: LedgerEntry, slug: string): boolean {
+  const anchored = anchorSlugOf(entry.target);
+  if (anchored) return anchored === slug;
+
+  const root = resolveAnchor(`{proj:${slug}}`);
+  if (root.state !== "anchored") return false;
+  return resolve(entry.target).startsWith(resolve(root.path));
+}
+
+function matchesFilter(entry: LedgerEntry, filter: LedgerFilter): boolean {
+  const at = new Date(entry.ts).getTime();
+  if (filter.since && at < filter.since.getTime()) return false;
+  if (filter.until && at > filter.until.getTime()) return false;
+  if (filter.project && !inProject(entry, filter.project)) return false;
+  if (filter.actor && entry.actor !== filter.actor) return false;
+  if (filter.machine && entry.machine !== filter.machine) return false;
+  if (filter.runtime && entry.runtime !== filter.runtime) return false;
+  if (filter.outcome && entry.outcome !== filter.outcome) return false;
+  if (filter.tool && entry.tool.toLowerCase() !== filter.tool.toLowerCase()) return false;
+  if (filter.target && !entry.target.includes(filter.target)) return false;
+  return true;
+}
+
+/**
+ * Matching entries oldest first, capped from the newest end — a limit that
+ * dropped the newest would answer "the last N changes" with the first ones.
+ */
+export function queryLedger(filter: LedgerFilter = {}): LedgerEntry[] {
+  const matched = readLedger().filter((entry) => matchesFilter(entry, filter));
+  return filter.limit === undefined ? matched : matched.slice(-filter.limit);
+}
+
+export function findEntry(id: string): LedgerEntry | null {
+  return readLedger().find((entry) => entry.id === id) ?? null;
+}
+
+/**
+ * Where the entry's target lives on this machine, or the reason it cannot be
+ * placed — a project this install has never registered resolves to nothing,
+ * and saying so is more useful than printing a slug as if it were a path.
+ */
+export function locate(entry: LedgerEntry): { path?: string; unresolvable?: string } {
+  const resolved = resolveAnchor(entry.target);
+  return resolved.state === "unresolvable"
+    ? { unresolvable: resolved.slug }
+    : { path: resolved.path };
+}
+
+export type ChangeShape =
+  | { kind: "hunks"; delta: LedgerDelta }
+  | { kind: "redacted" }
+  | { kind: "truncated" }
+  | { kind: "none" };
+
+/**
+ * What the entry can say about its own change. The three empty cases are kept
+ * apart because they mean different things: contents deliberately withheld, a
+ * change too large to keep, and an action that never landed at all.
+ */
+export function changeShape(entry: LedgerEntry): ChangeShape {
+  if (!entry.delta) return { kind: "none" };
+  if (entry.delta.redacted) return { kind: "redacted" };
+  if (entry.delta.truncated) return { kind: "truncated" };
+  return { kind: "hunks", delta: entry.delta };
+}
+
+/**
+ * Whether the change this entry recorded is still the state of the file.
+ *
+ * The comparison is against the hashes the entry already carries, not a replay
+ * from a stored before-image — the ledger keeps the change, not the prior file,
+ * so there is nothing to replay from unless the file happens to be sitting at
+ * its before-state again. `reverted` is exactly that case, and there the delta
+ * can be run forward for real, which is why it reports whether it did.
+ */
+export type Standing =
+  | { state: "in-place" }
+  | { state: "reverted"; replays: boolean }
+  | { state: "superseded"; hash: string }
+  | { state: "missing" }
+  | { state: "unknown"; why: string };
+
+function hashOf(content: string): string {
+  return new Bun.CryptoHasher("sha256").update(content, "utf-8").digest("hex");
+}
+
+function replaysToAfter(entry: LedgerEntry, onDisk: string): boolean {
+  if (!entry.delta || !entry.after) return false;
+  const rebuilt = applyDelta(onDisk, entry.delta);
+  return rebuilt !== null && hashOf(rebuilt) === entry.after.hash;
+}
+
+export function standing(entry: LedgerEntry): Standing {
+  if (!entry.after) return { state: "unknown", why: "the action never landed" };
+
+  const found = locate(entry);
+  if (!found.path)
+    return { state: "unknown", why: `unknown project ${found.unresolvable}` };
+  if (!existsSync(found.path)) return { state: "missing" };
+
+  const onDisk = readFileSync(found.path, "utf-8");
+  const hash = hashOf(onDisk);
+  if (hash === entry.after.hash) return { state: "in-place" };
+  if (entry.before && hash === entry.before.hash)
+    return { state: "reverted", replays: replaysToAfter(entry, onDisk) };
+  return { state: "superseded", hash };
+}
+
+/**
+ * What the record itself says became of a change, as opposed to what the disk
+ * says now.
+ *
+ * `standing` can only describe the present, so any entry that is not the newest
+ * for its target reads as superseded — true, and nearly content-free, since it
+ * says only that something happened afterwards. The ledger already holds the
+ * whole per-target chain, and that answers the question worth asking: whether a
+ * later action put the file back the way this one found it, and which action
+ * that was. It stays true no matter how many edits come after.
+ */
+export type ChainVerdict =
+  | { state: "latest" }
+  | { state: "undone"; by: string; at: string }
+  | { state: "followed"; by: string; at: string };
+
+/**
+ * Deliberately takes no entry list. A chain computed over a filtered query
+ * would report `latest` for an entry the filter merely hid the successor of,
+ * so there is no parameter here through which that mistake can be made.
+ */
+export function chainVerdict(entry: LedgerEntry): ChainVerdict {
+  const all = readLedger();
+  const position = all.findIndex((candidate) => candidate.id === entry.id);
+  const later = all
+    .slice(position + 1)
+    .filter((candidate) => candidate.target === entry.target);
+  if (later.length === 0) return { state: "latest" };
+
+  const undo = undoingEntry(entry, later);
+  const next = undo ?? later[0];
+  return { state: undo ? "undone" : "followed", by: next.id, at: next.ts };
+}
+
+/**
+ * The first later action that left the file as this one found it. An action
+ * that never landed changed nothing to undo, and one that created the file is
+ * undone by a deletion, which this ledger does not record.
+ */
+function undoingEntry(entry: LedgerEntry, later: LedgerEntry[]): LedgerEntry | undefined {
+  if (!entry.before || !entry.after) return undefined;
+  return later.find((candidate) => candidate.after?.hash === entry.before?.hash);
+}
+
+export interface LedgerStats {
+  total: number;
+  span: { first: string; last: string } | null;
+  byOutcome: Record<string, number>;
+  byRuntime: Record<string, number>;
+  byActor: Record<string, number>;
+  byTool: Record<string, number>;
+  topTargets: { target: string; count: number }[];
+}
+
+function tally<T>(items: T[], key: (item: T) => string): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const item of items) {
+    const k = key(item);
+    counts[k] = (counts[k] ?? 0) + 1;
+  }
+  return counts;
+}
+
+function rank(
+  counts: Record<string, number>,
+  top: number
+): { target: string; count: number }[] {
+  return Object.entries(counts)
+    .map(([target, count]) => ({ target, count }))
+    .sort((a, b) => b.count - a.count || a.target.localeCompare(b.target))
+    .slice(0, top);
+}
+
+export function summarize(entries: LedgerEntry[], topTargets = 10): LedgerStats {
+  const first = entries.at(0);
+  const last = entries.at(-1);
+  return {
+    total: entries.length,
+    span: first && last ? { first: first.ts, last: last.ts } : null,
+    byOutcome: tally(entries, (e) => e.outcome),
+    byRuntime: tally(entries, (e) => e.runtime),
+    byActor: tally(entries, (e) => e.actor),
+    byTool: tally(entries, (e) => e.tool),
+    topTargets: rank(
+      tally(entries, (e) => e.target),
+      topTargets
+    ),
+  };
+}
+
+/**
+ * A window expressed the way someone asks for one: a duration back from now
+ * ("7d", "24h") or a calendar date. Nothing else is guessed at — an
+ * unparseable spec is reported rather than silently treated as no filter,
+ * which would answer a narrow question with the whole ledger.
+ */
+export function parseSince(spec: string, now: Date = new Date()): Date | null {
+  const duration = /^(\d+)([smhdw])$/.exec(spec.trim());
+  if (duration) {
+    const unit = { s: 1e3, m: 6e4, h: 36e5, d: 864e5, w: 6048e5 }[duration[2]];
+    if (!unit) return null;
+    return new Date(now.getTime() - Number(duration[1]) * unit);
+  }
+
+  const at = new Date(spec);
+  return Number.isNaN(at.getTime()) ? null : at;
+}