portable-agent-layer 0.68.0 → 0.70.0

package/src/cli/server.ts

@@ -0,0 +1,195 @@
+/**
+ * pal cli server — start, stop and inspect the local ledger page.
+ *
+ * The server itself is src/tools/ledger/server.ts, run detached so it
+ * outlives the shell that started it. This file only owns the lifecycle:
+ * spawning, waiting for it to answer, remembering its pid, and killing it.
+ */
+
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { spawnDetachedInference } from "../hooks/lib/detached-inference";
+import { paths } from "../hooks/lib/paths";
+import { DEFAULT_PORT, LOOPBACK, type ServerStatus } from "../tools/ledger/server";
+
+interface ServerState {
+  pid: number;
+  port: number;
+  startedAt: string;
+}
+
+const SERVER_SCRIPT = resolve(import.meta.dir, "..", "tools", "ledger", "server.ts");
+const STARTUP_TIMEOUT_MS = 3000;
+const PROBE_TIMEOUT_MS = 500;
+
+export async function runServer(args: string[]): Promise<number> {
+  const [sub, ...rest] = args;
+  switch (sub) {
+    case "start":
+      return cmdStart(rest);
+    case "stop":
+      return cmdStop();
+    case "status":
+      return cmdStatus();
+    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 server <subcommand>
+
+  Subcommands:
+    start [--port <n>]         Start the ledger page in the background (default port ${DEFAULT_PORT})
+    stop                       Stop it
+    status                     Show whether it is running, and where
+
+  The page listens on ${LOOPBACK} only.
+`);
+}
+
+function url(port: number): string {
+  return `http://${LOOPBACK}:${port}/`;
+}
+
+function readState(): ServerState | null {
+  const file = paths.serverState();
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, "utf-8")) as ServerState;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state: ServerState): void {
+  writeFileSync(paths.serverState(), JSON.stringify(state, null, 2), "utf-8");
+}
+
+function clearState(): void {
+  const file = paths.serverState();
+  if (existsSync(file)) unlinkSync(file);
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function probe(port: number): Promise<ServerStatus | null> {
+  try {
+    const res = await fetch(`${url(port)}api/status`, {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+    return res.ok ? ((await res.json()) as ServerStatus) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function waitUntilAnswering(port: number): Promise<ServerStatus | null> {
+  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const status = await probe(port);
+    if (status) return status;
+    await Bun.sleep(100);
+  }
+  return null;
+}
+
+function parsePort(args: string[]): number | string {
+  const { values } = parseArgs({ args, options: { port: { type: "string" } } });
+  if (values.port === undefined) return DEFAULT_PORT;
+  const port = Number(values.port);
+  return Number.isInteger(port) && port > 0 && port < 65536
+    ? port
+    : `--port must be a port number, got ${values.port}`;
+}
+
+async function cmdStart(args: string[]): Promise<number> {
+  const port = parsePort(args);
+  if (typeof port === "string") return fail(port);
+
+  const running = await runningServer();
+  if (running) {
+    console.log(`Already running at ${url(running.port)} (pid ${running.pid})`);
+    return 0;
+  }
+
+  spawnDetachedInference(SERVER_SCRIPT, [`--port=${port}`], "ledger-server");
+  const status = await waitUntilAnswering(port);
+  if (!status)
+    return fail(
+      `The ledger page did not answer on port ${port} within ${STARTUP_TIMEOUT_MS / 1000}s. Is the port free?`
+    );
+
+  writeState({ pid: status.pid, port, startedAt: status.startedAt });
+  console.log(url(port));
+  return 0;
+}
+
+/** The state file is a claim; the process answering on that port is the fact. */
+async function runningServer(): Promise<ServerState | null> {
+  const state = readState();
+  if (!state || !alive(state.pid)) return null;
+  return (await probe(state.port)) ? state : null;
+}
+
+async function cmdStop(): Promise<number> {
+  const state = readState();
+  if (!state) {
+    console.log("Not running.");
+    return 0;
+  }
+  if (alive(state.pid)) {
+    process.kill(state.pid);
+    console.log(`Stopped pid ${state.pid}.`);
+  } else {
+    console.log(`Pid ${state.pid} was already gone; cleared the stale record.`);
+  }
+  clearState();
+  return 0;
+}
+
+async function cmdStatus(): Promise<number> {
+  const state = readState();
+  if (!state) {
+    console.log("Not running.");
+    return 1;
+  }
+  const status = alive(state.pid) ? await probe(state.port) : null;
+  if (!status) {
+    console.log(
+      `Not running (stale record for pid ${state.pid}; run \`pal cli server stop\`).`
+    );
+    return 1;
+  }
+  console.log(`
+  ${url(status.port)}
+  pid          ${status.pid}
+  started      ${status.startedAt}
+  ledger       ${status.ledgerFiles} file(s)
+  machine      ${status.machine}
+`);
+  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/hooks/lib/paths.ts

@@ -62,6 +62,7 @@ export const paths = {
   work: () => ensureDir(home("memory", "work")),
   backups: () => ensureDir(home("backups")),
   debug: () => ensureDir(home("debug")),
+  serverState: () => home("server.json"),
 } as const;
 
 // Platform directories (env override or cross-platform defaults)
@@ -87,6 +88,7 @@ export const assets = {
   copilotHooksTemplate: () => pkg("assets", "templates", "hooks.copilot.json"),
   codexHooksTemplate: () => pkg("assets", "templates", "hooks.codex.json"),
   codexRulesTemplate: () => pkg("assets", "templates", "rules.codex.rules"),
+  ledgerPageTemplate: () => pkg("assets", "templates", "ledger-page.html"),
   statuslineScriptBash: () => pkg("assets", "statusline.sh"),
   statuslineScriptPs1: () => pkg("assets", "statusline.ps1"),
   agentTools: () => pkg("src", "tools", "agent"),

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,318 @@
+/**
+ * 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.
+ */
+/** The change as a reader would want it summarised: a line count, or why there is none. */
+export 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}`;
+    }
+  }
+}
+
+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;
+}