@a2f0/agent-tool 0.1.30 → 0.1.32

package/src/processes/ledger.ts

@@ -0,0 +1,123 @@
+// Long-running processes agent-tool started for a repository, recorded one file each under the
+// Git common directory, so every worktree and clone-local session sees the same list and it
+// survives branch switches. A record names the process group agent-tool created; whether that
+// group still runs is decided from the live process table, never from the record alone.
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { git } from "../workflows/core";
+import { carrying, type ProcessRow } from "./table";
+
+export interface ProcessRecord {
+  schemaVersion: 1;
+  id: string;
+  label: string | null;
+  /** The group leader agent-tool spawned; its pid is the group id. */
+  pid: number;
+  /** The leader's start time as `ps` prints it, which tells a reused pid apart. */
+  started: string;
+  command: string[];
+  cwd: string;
+  log: string;
+  startedAt: string;
+  /** Started to outlive the work, such as a dev server the user asked to keep: teardown reports it without failing. */
+  keep: boolean;
+  /** Members seen while the leader ran, by start time, so they are still known once it has gone. */
+  members?: { pid: number; started: string }[];
+}
+
+export type ProcessState = "running" | "orphaned" | "exited" | "replaced";
+
+export function ledgerDirectory(cwd = process.cwd()): string {
+  return path.join(git(["rev-parse", "--path-format=absolute", "--git-common-dir"], cwd), "agent-tool", "processes");
+}
+
+export function newId(): string { return randomUUID().slice(0, 8); }
+
+export function saveRecord(directory: string, record: ProcessRecord): void {
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const file = path.join(directory, `${record.id}.json`), temporary = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+  renameSync(temporary, file);
+}
+
+export function removeRecord(directory: string, id: string): void { rmSync(path.join(directory, `${id}.json`), { force: true }); }
+
+const ID = /^[a-f0-9]{8}$/;
+// Generous enough for any argv the OS accepts plus the member list, which keeps only live members.
+const MAX_RECORD_BYTES = 4 * 1024 * 1024;
+const MAX_MEMBERS = 1000;
+
+function valid(value: unknown): value is ProcessRecord {
+  const record = value as ProcessRecord;
+  return !!record && record.schemaVersion === 1 && typeof record.id === "string" && ID.test(record.id) && Number.isInteger(record.pid) && record.pid > 1
+    && typeof record.started === "string" && Array.isArray(record.command) && record.command.every(arg => typeof arg === "string")
+    && typeof record.cwd === "string" && typeof record.log === "string" && typeof record.startedAt === "string"
+    && (record.label === null || typeof record.label === "string") && typeof record.keep === "boolean"
+    && (record.members === undefined || (Array.isArray(record.members) && record.members.every(member => Number.isInteger(member?.pid) && typeof member.started === "string")));
+}
+
+/** Every record, and the files that could not be read as one. */
+export function readRecords(directory: string): { records: ProcessRecord[]; skipped: { file: string; reason: string }[] } {
+  const records: ProcessRecord[] = [], skipped: { file: string; reason: string }[] = [];
+  for (const file of existsSync(directory) ? readdirSync(directory).filter(name => name.endsWith(".json")).sort() : []) {
+    try {
+      const full = path.join(directory, file), stat = lstatSync(full);
+      if (!stat.isFile() || stat.size > MAX_RECORD_BYTES) throw new Error("Not a process record file.");
+      const record = JSON.parse(readFileSync(full, "utf8")) as unknown;
+      if (!valid(record) || `${record.id}.json` !== file) throw new Error("Invalid process record.");
+      records.push(record);
+    } catch (error) { skipped.push({ file, reason: (error as Error).message }); }
+  }
+  return { records, skipped };
+}
+
+/**
+ * The processes that belong to a record. While its leader runs, that is its group and the live
+ * descendants of the group. Once the leader has gone its pid, and so the group id, can be reused,
+ * so a leaderless member counts only when it was seen while the leader ran (same pid and start
+ * time) or carries the record's AGENT_TOOL_PROCESS id; descendants of counted members count too.
+ */
+/** The live leaders of records other than `record`, which own their own process trees. */
+export function claimedBy(record: ProcessRecord, table: Map<number, ProcessRow>, others: ProcessRecord[]): Set<number> {
+  return new Set(others.filter(other => other.id !== record.id && table.get(other.pid)?.started === other.started).map(other => other.pid));
+}
+
+export function membersOf(record: ProcessRecord, table: Map<number, ProcessRow>, others: ProcessRecord[] = []): { state: ProcessState; members: ProcessRow[] } {
+  // Another record's live leader, and everything under it, belongs to that record, even when it
+  // was started from inside this one (a nested `proc start --keep`).
+  const claimed = claimedBy(record, table, others);
+  const leader = table.get(record.pid);
+  const ours = !!leader && leader.started === record.started;
+  const seen = new Set((record.members ?? []).map(member => `${member.pid} ${member.started}`));
+  const known = (row: ProcessRow) => seen.has(`${row.pid} ${row.started}`);
+  let group: ProcessRow[] = [];
+  // Another process now holding the leader's pid makes the group id unreliable too: only
+  // remembered members still count.
+  if (ours) group = [...table.values()].filter(row => row.pgid === record.pid);
+  else if (!leader) {
+    const candidates = [...table.values()].filter(row => row.pgid === record.pid);
+    const tagged = carrying(candidates.filter(row => !known(row)).map(row => row.pid), "AGENT_TOOL_PROCESS", record.id);
+    group = candidates.filter(row => known(row) || tagged.has(row.pid));
+  }
+  // Members seen before, wherever they are now: a descendant that left the group keeps its
+  // identity after its parent exits and it is no longer anyone's descendant.
+  const members = new Map([...group, ...[...table.values()].filter(known)].filter(row => !claimed.has(row.pid)).map(row => [row.pid, row]));
+  // Children that left the group (setsid, a new process group) are still reached through their parents.
+  for (let grew = true; grew;) {
+    grew = false;
+    for (const row of table.values()) if (!members.has(row.pid) && !claimed.has(row.pid) && members.has(row.ppid)) { members.set(row.pid, row); grew = true; }
+  }
+  const list = [...members.values()].sort((a, b) => a.pid - b.pid);
+  return { state: ours ? "running" : list.length ? "orphaned" : leader ? "replaced" : "exited", members: list };
+}
+
+/** Remembers the live members seen while the leader runs, for when it has gone; dead ones are dropped. */
+export function observe(directory: string, record: ProcessRecord, state: ProcessState, members: ProcessRow[]): void {
+  if (state !== "running") return;
+  const next = members.slice(0, MAX_MEMBERS).map(row => ({ pid: row.pid, started: row.started }));
+  const key = (list: { pid: number; started: string }[]) => list.map(member => `${member.pid} ${member.started}`).sort().join("\n");
+  if (key(next) === key(record.members ?? [])) return;
+  record.members = next;
+  try { saveRecord(directory, record); } catch { /* Best effort: an unrecorded member is only found while the leader runs. */ }
+}

package/src/processes/table.ts

@@ -0,0 +1,111 @@
+// The machine's processes as agent-tool sees them: identity (pid, parent, group and start time),
+// working directory, and listening TCP ports. Read through `ps`, `lsof` and, on Linux, `/proc`,
+// so it needs nothing beyond the operating system.
+import { execFileSync } from "node:child_process";
+import { readFileSync, readlinkSync } from "node:fs";
+
+export interface ProcessRow { pid: number; ppid: number; pgid: number; started: string; command: string }
+
+// One locale and time zone, so start times read the same in every shell that compares them.
+const C_LOCALE = { ...process.env, LC_ALL: "C", LANG: "C", TZ: "UTC" };
+// `stat` is one token; `lstart` prints a fixed-width date of five fields, such as `Fri Oct 30 21:43:01 2026`.
+const ROW = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+([A-Z][a-z]{2}\s+[A-Z][a-z]{2}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s(.*)$/;
+
+/**
+ * Rows of `ps -o pid=,ppid=,pgid=,stat=,lstart=,command=`. Zombies are left out: they have
+ * exited, cannot be signalled, and may never be reaped where PID 1 does not reap orphans.
+ */
+export function parseRows(text: string): ProcessRow[] {
+  return text.split("\n").flatMap(line => {
+    const match = ROW.exec(line);
+    if (!match || match[4]!.startsWith("Z")) return [];
+    return [{ pid: Number(match[1]), ppid: Number(match[2]), pgid: Number(match[3]), started: match[5]!.replace(/\s+/g, " "), command: match[6]!.trim() }];
+  });
+}
+
+/** Every live process, by pid. */
+export function processTable(): Map<number, ProcessRow> {
+  const text = execFileSync("ps", ["-A", "-o", "pid=,ppid=,pgid=,stat=,lstart=,command="], { encoding: "utf8", env: C_LOCALE, maxBuffer: 64 * 1024 * 1024 });
+  return new Map(parseRows(text).map(row => [row.pid, row]));
+}
+
+/** When a running process started, as `ps` prints it, or undefined once it has gone. */
+export function startOf(pid: number): string | undefined {
+  try {
+    const text = execFileSync("ps", ["-o", "stat=,lstart=", "-p", String(pid)], { encoding: "utf8", env: C_LOCALE, stdio: ["ignore", "pipe", "ignore"] }).trim();
+    const match = /^(\S+)\s+(.+)$/.exec(text);
+    return match && !match[1]!.startsWith("Z") ? match[2]!.replace(/\s+/g, " ") : undefined;
+  } catch { return undefined; }
+}
+
+/** lsof's output, or undefined when it is missing or failed rather than finding nothing. */
+function lsof(args: string[]): string | undefined {
+  try {
+    return execFileSync("lsof", args, { encoding: "utf8", env: C_LOCALE, stdio: ["ignore", "pipe", "pipe"], maxBuffer: 64 * 1024 * 1024 });
+  } catch (error) {
+    // lsof exits 1 when nothing matches, perhaps with warnings. With another diagnostic, any other status, a
+    // missing binary or a signal, the inspection failed and may have missed what it looked for.
+    const result = error as { status?: number | null; stdout?: string; stderr?: string };
+    const failures = (result.stderr ?? "").split("\n").filter(line => line.trim() && !line.startsWith("lsof: WARNING"));
+    return result.status === 1 && failures.length === 0 ? result.stdout ?? "" : undefined;
+  }
+}
+
+/** Parses `lsof -F pn` output into the names each pid holds. */
+export function parseFields(text: string): Map<number, string[]> {
+  const found = new Map<number, string[]>();
+  let pid = 0;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("p")) pid = Number(line.slice(1));
+    else if (line.startsWith("n") && pid) found.set(pid, [...found.get(pid) ?? [], line.slice(1)]);
+  }
+  return found;
+}
+
+/** Each process's working directory; `available` is false when neither lsof nor /proc can say. */
+export function workingDirectories(pids: Iterable<number>): { available: boolean; cwd: Map<number, string> } {
+  const text = lsof(["-a", "-d", "cwd", "-F", "pn"]);
+  if (text !== undefined) return { available: true, cwd: new Map([...parseFields(text)].map(([pid, names]) => [pid, names[0]!])) };
+  if (process.platform !== "linux") return { available: false, cwd: new Map() };
+  const cwd = new Map<number, string>();
+  for (const pid of pids) { try { cwd.set(pid, readlinkSync(`/proc/${pid}/cwd`)); } catch { /* Gone or not ours. */ } }
+  return { available: true, cwd };
+}
+
+/** The TCP addresses each process listens on; `available` is false without lsof. */
+export function listeningPorts(): { available: boolean; ports: Map<number, string[]> } {
+  const text = lsof(["-nP", "-iTCP", "-sTCP:LISTEN", "-F", "pn"]);
+  if (text === undefined) return { available: false, ports: new Map() };
+  return { available: true, ports: new Map([...parseFields(text)].map(([pid, names]) => [pid, [...new Set(names)]])) };
+}
+
+/** This process and every process above it, which teardown never reports or stops. */
+export function ancestors(table: Map<number, ProcessRow>, pid = process.pid): Set<number> {
+  const found = new Set<number>();
+  for (let current: number | undefined = pid; current && !found.has(current); current = table.get(current)?.ppid) found.add(current);
+  return found;
+}
+
+/**
+ * The processes among `pids` whose environment carries `NAME=value`, as `proc start` sets for
+ * everything it launches. macOS hides the environment of protected system binaries, which then
+ * never match.
+ */
+export function carrying(pids: number[], name: string, value: string): Set<number> {
+  const found = new Set<number>(), entry = `${name}=${value}`;
+  if (pids.length === 0) return found;
+  if (process.platform === "linux") {
+    for (const pid of pids) {
+      try { if (readFileSync(`/proc/${pid}/environ`, "latin1").split("\0").includes(entry)) found.add(pid); } catch { /* Gone or not ours. */ }
+    }
+    return found;
+  }
+  try {
+    const text = execFileSync("ps", ["-E", "-ww", "-o", "pid=,command=", "-p", pids.join(",")], { encoding: "utf8", env: C_LOCALE, stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024 });
+    for (const line of text.split("\n")) {
+      const match = /^\s*(\d+)\s(.*)$/.exec(line);
+      if (match && ` ${match[2]} `.includes(` ${entry} `)) found.add(Number(match[1]));
+    }
+  } catch { /* None readable. */ }
+  return found;
+}

package/src/screenshots/build.ts

@@ -0,0 +1,271 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, rmSync } from "node:fs";
+import path from "node:path";
+import { pngSize } from "../images/png";
+import { assertNoLinks, replaceFile } from "../system/files";
+import type { ScreenshotsConfig, ScreenshotTarget } from "./config";
+import type { ScreenshotCapture, ScreenshotEntry, ScreenshotManifest } from "./manifest";
+
+/** The record the take-screenshots skill keeps beside a shared capture. */
+export const CAPTURE_RECORD = "capture.json";
+const MANIFEST = "manifest.json";
+const IMAGES = "img";
+
+interface CaptureRecord { status?: unknown; commit?: unknown; dirty?: unknown; finishedAt?: unknown; args?: unknown }
+export interface CaptureSummary extends ScreenshotCapture { partial: string[] }
+
+function readRecord(source: string): string | undefined {
+  try { return readFileSync(path.join(source, CAPTURE_RECORD), "utf8"); } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT" || (error as NodeJS.ErrnoException).code === "ENOTDIR") return undefined;
+    throw error;
+  }
+}
+
+/**
+ * The shared-capture guard. Every capture writes a `running` record before it
+ * touches an image, so a `complete` record that is unchanged before and after
+ * copying proves no capture overlapped the copy. A plain directory without a
+ * record (CI, an unlinked clone) copies as is; a linked, non-empty store
+ * without one is refused, since its images name no commit.
+ */
+export function checkCapture(root: string, source: string, raw: string | undefined): CaptureSummary | null {
+  if (raw === undefined) {
+    // Linked anywhere below the repository root, as `.screenshots` or through a parent directory.
+    const linked = resolved(source) !== path.join(resolved(root), path.relative(root, source));
+    let contents: string[] = [];
+    try { contents = readdirSync(source); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+    if (linked && contents.length > 0) throw new Error("The shared screenshots have no capture record; capture once through the take-screenshots skill.");
+    return null;
+  }
+  let record: CaptureRecord;
+  try { record = JSON.parse(raw) as CaptureRecord; } catch { throw new Error(`The shared screenshot capture record ${CAPTURE_RECORD} is not JSON; recapture.`); }
+  if (!record || typeof record !== "object") throw new Error(`The shared screenshot capture record ${CAPTURE_RECORD} is not an object; recapture.`);
+  if (record.status !== "complete") throw new Error(`The shared screenshot capture is ${String(record.status)}; wait for it or recapture.`);
+  if (typeof record.commit !== "string" || !/^[0-9a-f]{40}$/.test(record.commit)) throw new Error("The shared screenshot capture record names no commit; recapture.");
+  if (record.dirty !== false) throw new Error("The shared screenshots were captured from uncommitted changes; recapture from a commit.");
+  const partial = Array.isArray(record.args) ? record.args.map(String) : [];
+  return { commit: record.commit, finishedAt: typeof record.finishedAt === "string" ? record.finishedAt : null, partial };
+}
+
+function select(config: ScreenshotsConfig, names: string[], out: string | undefined): [string, ScreenshotTarget][] {
+  const available = Object.keys(config.targets);
+  if (!available.length) throw new Error("agent-tool.json defines no screenshots.targets.");
+  for (const name of names) if (!config.targets[name]) throw new Error(`Unknown screenshots target '${name}'; expected one of: ${available.join(", ")}.`);
+  if (out !== undefined && new Set(names).size !== 1) throw new Error("--out needs exactly one screenshots target.");
+  const selected = names.length ? [...new Set(names)] : available.filter(name => config.targets[name]!.dir !== null);
+  if (!selected.length) throw new Error("No screenshots target has a dir; name one and pass --out <directory>.");
+  return selected.map(name => [name, config.targets[name]!]);
+}
+
+/** The path with every existing ancestor's links resolved, so overlap checks see where writes really land. */
+function resolved(file: string): string {
+  const parts: string[] = [];
+  let current = path.resolve(file);
+  for (;;) {
+    try { return path.join(realpathSync(current), ...parts.reverse()); } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return path.join(current, ...parts.reverse());
+    parts.push(path.basename(current));
+    current = parent;
+  }
+}
+/** Whether either path is the other or contains it. */
+function overlaps(first: string, second: string): boolean {
+  const a = first.toLowerCase(), b = second.toLowerCase();
+  return a === b || a.startsWith(`${b}${path.sep}`) || b.startsWith(`${a}${path.sep}`);
+}
+
+/** The first link anywhere in the capture tree whose target overlaps an output, following linked directories once. */
+function linkedInto(source: string, outputs: string[]): string | undefined {
+  const visited = new Set<string>();
+  const walk = (dir: string): string | undefined => {
+    let real: string;
+    try { real = realpathSync(dir); } catch { return undefined; }
+    if (visited.has(real)) return undefined;
+    visited.add(real);
+    let names: string[];
+    try { names = readdirSync(dir); } catch { return undefined; }
+    for (const name of names) {
+      const entry = path.join(dir, name), stats = lstatSync(entry, { throwIfNoEntry: false });
+      if (stats?.isSymbolicLink() && outputs.some(output => overlaps(resolved(entry), output))) return entry;
+      if (stats?.isDirectory() || (stats?.isSymbolicLink() && lstatSync(resolved(entry), { throwIfNoEntry: false })?.isDirectory())) {
+        const found = walk(entry);
+        if (found) return found;
+      }
+    }
+    return undefined;
+  };
+  return walk(source);
+}
+
+function sameBytes(file: string, bytes: Uint8Array): boolean {
+  const stats = lstatSync(file, { throwIfNoEntry: false });
+  return !!stats?.isFile() && stats.size === bytes.length && Buffer.compare(readFileSync(file), bytes) === 0;
+}
+
+/** Files below `dir`, relative to it, without following links; links count as files to remove. */
+function ownedFiles(dir: string): string[] {
+  const stats = lstatSync(dir, { throwIfNoEntry: false });
+  if (!stats) return [];
+  if (!stats.isDirectory()) return [""];
+  return readdirSync(dir).sort().flatMap(name => ownedFiles(path.join(dir, name)).map(file => file ? path.join(name, file) : name));
+}
+
+function removeEmptyDirectories(dir: string, keep: boolean): void {
+  const stats = lstatSync(dir, { throwIfNoEntry: false });
+  if (!stats?.isDirectory()) return;
+  for (const name of readdirSync(dir)) removeEmptyDirectories(path.join(dir, name), false);
+  if (!keep && readdirSync(dir).length === 0) rmdirSync(dir);
+}
+
+/** Removes everything the target owns: the manifest and the image tree. Other files in the directory stay. */
+function removeOutputs(dir: string): void {
+  rmSync(path.join(dir, MANIFEST), { force: true });
+  rmSync(path.join(dir, IMAGES), { force: true, recursive: true });
+}
+
+interface Staged {
+  name: string;
+  dir: string;
+  absolute: string;
+  manifest: ScreenshotManifest;
+  written: string[];
+  unchanged: string[];
+  keep: Set<string>;
+}
+
+function stageTarget(root: string, source: string, name: string, target: ScreenshotTarget, dir: string, base: string, capture: CaptureSummary | null): Staged {
+  const absolute = path.resolve(root, dir);
+  const staged: Staged = { name, dir, absolute, manifest: { schemaVersion: 1, projects: [], themes: [], screens: [], entries: [], capture: null }, written: [], unchanged: [], keep: new Set() };
+  const entries: ScreenshotEntry[] = [];
+  for (const project of target.projects) {
+    for (const theme of target.themes) {
+      for (const screen of target.screens) {
+        const file = path.join(source, project.dir, theme, `${screen.name}.png`);
+        let bytes: Uint8Array;
+        try { bytes = readFileSync(file); } catch (error) {
+          if (["ENOENT", "ENOTDIR"].includes((error as NodeJS.ErrnoException).code ?? "")) continue;
+          throw error;
+        }
+        const size = pngSize(bytes);
+        if (!size) throw new Error(`${path.relative(root, file)} is not a PNG image.`);
+        const relative = path.join(IMAGES, project.name, theme, `${screen.name}.png`);
+        const destination = path.join(absolute, relative);
+        assertNoLinks(base, destination);
+        if (sameBytes(destination, bytes)) staged.unchanged.push(path.join(dir, relative));
+        else {
+          mkdirSync(path.dirname(destination), { recursive: true });
+          replaceFile(destination, bytes);
+          staged.written.push(path.join(dir, relative));
+        }
+        staged.keep.add(relative);
+        const version = createHash("sha256").update(bytes).digest("hex").slice(0, 8);
+        entries.push({ project: project.name, theme, name: screen.name, src: `${target.urlPrefix}${IMAGES}/${project.name}/${theme}/${screen.name}.png?v=${version}`, ...size });
+      }
+    }
+  }
+  const has = (key: keyof ScreenshotEntry, value: string) => entries.some(entry => entry[key] === value);
+  staged.manifest = {
+    schemaVersion: 1,
+    projects: target.projects.filter(project => has("project", project.name)).map(({ name, label, frame }) => frame ? { name, label, frame } : { name, label }),
+    themes: target.themes.filter(theme => has("theme", theme)).map(theme => ({ name: theme, label: theme.charAt(0).toUpperCase() + theme.slice(1).replaceAll("-", " ") })),
+    screens: target.screens.filter(screen => has("name", screen.name)).map(({ name, label, alt }) => alt ? { name, label, alt } : { name, label }),
+    entries,
+    capture: capture && { commit: capture.commit, finishedAt: capture.finishedAt },
+  };
+  return staged;
+}
+
+export interface ScreenshotsTargetReceipt {
+  name: string;
+  dir: string;
+  manifest: string;
+  entries: number;
+  projects: string[];
+  written: string[];
+  unchanged: number;
+  removed: string[];
+}
+export interface ScreenshotsReceipt { source: string; capture: CaptureSummary | null; targets: ScreenshotsTargetReceipt[] }
+
+/**
+ * Stages the selected targets from the capture source. Images are copied only
+ * when their bytes differ, files the target owns but no longer lists are
+ * removed, and the manifest is written last, atomically, once the capture
+ * record is confirmed unchanged. Any failure removes the targets' outputs, so
+ * a site never builds from a partial or unverified gallery.
+ */
+export function buildScreenshots(root: string, config: ScreenshotsConfig, names: string[], out?: string, hooks: { afterCopy?: () => void } = {}): ScreenshotsReceipt {
+  const selected = select(config, names, out);
+  const source = path.resolve(root, config.source);
+  // The source is usually a link to the shared store; compare where both really are.
+  const sources = [source, resolved(source)];
+  const claimed: { name: string; dirs: string[] }[] = [];
+  const plans = selected.map(([name, target]) => {
+    const dir = out ?? target.dir;
+    if (dir === null) throw new Error(`Screenshots target '${name}' has no dir; pass --out <directory>.`);
+    const absolute = path.resolve(root, dir);
+    const dirs = [absolute, resolved(absolute)];
+    // Pruning or cleanup in an overlapping directory would delete captures or another target's images.
+    if (dirs.some(item => sources.some(other => overlaps(item, other)))) throw new Error(`Screenshots target '${name}' overlaps the capture source.`);
+    const owner = claimed.find(other => other.dirs.some(item => dirs.some(mine => overlaps(item, mine))));
+    if (owner) throw new Error(`Screenshots targets '${owner.name}' and '${name}' write overlapping directories.`);
+    claimed.push({ name, dirs });
+    // An explicit --out is the caller's choice; configured directories are checked from the repository root.
+    const base = out === undefined ? root : absolute;
+    assertNoLinks(base, path.join(absolute, IMAGES));
+    assertNoLinks(base, path.join(absolute, MANIFEST));
+    return { name, target, dir, absolute, base };
+  });
+  // A capture linked into an output would be pruned or cleaned up with it.
+  const outputs = plans.flatMap(plan => [plan.absolute, resolved(plan.absolute)]);
+  const linked = linkedInto(source, outputs);
+  if (linked) throw new Error(`${path.relative(root, linked)} links into a screenshots output directory.`);
+  let staged: Staged[] = [];
+  try {
+    const before = readRecord(source);
+    const capture = checkCapture(root, source, before);
+    staged = plans.map(plan => stageTarget(root, source, plan.name, plan.target, plan.dir, plan.base, capture));
+    hooks.afterCopy?.();
+    if (readRecord(source) !== before) throw new Error("A screenshot capture started while copying; build again once it finishes.");
+    const targets = staged.map(item => {
+      const removed = ownedFiles(path.join(item.absolute, IMAGES)).filter(file => !item.keep.has(path.join(IMAGES, file)));
+      for (const file of removed) rmSync(path.join(item.absolute, IMAGES, file), { force: true });
+      removeEmptyDirectories(path.join(item.absolute, IMAGES), item.keep.size > 0);
+      if (!item.keep.size) rmSync(path.join(item.absolute, IMAGES), { force: true, recursive: true });
+      const manifestFile = path.join(item.absolute, MANIFEST);
+      const bytes = Buffer.from(`${JSON.stringify(item.manifest, null, 2)}\n`);
+      mkdirSync(item.absolute, { recursive: true });
+      if (sameBytes(manifestFile, bytes)) item.unchanged.push(path.join(item.dir, MANIFEST));
+      else { replaceFile(manifestFile, bytes); item.written.push(path.join(item.dir, MANIFEST)); }
+      return {
+        name: item.name, dir: item.dir, manifest: path.join(item.dir, MANIFEST), entries: item.manifest.entries.length,
+        projects: item.manifest.projects.map(project => project.name), written: item.written, unchanged: item.unchanged.length,
+        removed: removed.map(file => path.join(item.dir, IMAGES, file)),
+      };
+    });
+    return { source: config.source, capture, targets };
+  } catch (error) {
+    for (const plan of plans) if (existsSync(plan.absolute)) removeOutputs(plan.absolute);
+    throw error;
+  }
+}
+
+/** One line per target for people; `--json` prints the receipt instead. */
+export function describeScreenshots(receipt: ScreenshotsReceipt): string {
+  const lines: string[] = [];
+  if (receipt.capture) {
+    const partial = receipt.capture.partial.length ? ` (partial: ${receipt.capture.partial.join(" ")})` : "";
+    lines.push(`Screenshots from ${receipt.capture.commit.slice(0, 10)}, captured ${receipt.capture.finishedAt ?? "at an unrecorded time"}${partial}.`);
+  }
+  for (const target of receipt.targets) {
+    const counts = `${target.written.length} written, ${target.unchanged} unchanged, ${target.removed.length} removed`;
+    lines.push(target.entries
+      ? `${target.name}: staged ${target.entries} screenshot(s) across ${target.projects.join(", ")} into ${target.dir} (${counts}).`
+      : `${target.name}: no screenshots in ${receipt.source}; wrote an empty manifest to ${target.manifest} (${counts}).`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/screenshots/config.ts

@@ -0,0 +1,94 @@
+/** The data-only `screenshots` section of agent-tool.json: captured screens staged into a site. */
+
+export type Frame = "phone" | "tablet" | "none";
+export interface ScreenshotProject {
+  name: string;
+  label: string;
+  /** The capture directory under the source, when it differs from the name. */
+  dir: string;
+  frame: Frame | null;
+}
+export interface ScreenshotScreen { name: string; label: string; alt: string | null }
+export interface ScreenshotTarget {
+  dir: string | null;
+  urlPrefix: string;
+  projects: ScreenshotProject[];
+  themes: string[];
+  screens: ScreenshotScreen[];
+}
+export interface ScreenshotsConfig { source: string; targets: Record<string, ScreenshotTarget> }
+
+export const SCREENSHOTS_DEFAULTS: ScreenshotsConfig = { source: ".screenshots", targets: {} };
+const NAME = /^[a-z0-9][a-z0-9-]*$/;
+const TARGET = /^[a-z][a-z0-9-]*$/;
+const FRAMES: Frame[] = ["phone", "tablet", "none"];
+
+type Json = Record<string, unknown>;
+function fail(setting: string): never { throw new Error(`Invalid config setting '${setting}'.`); }
+function object(value: unknown, setting: string, allowed?: string[]): Json {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(setting);
+  if (allowed) for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unknown ${setting} setting '${key}'.`);
+  return value as Json;
+}
+function text(value: unknown): value is string { return typeof value === "string" && value.trim().length > 0 && !/[\r\n]/.test(value); }
+/** Repository-relative and inside it: no absolute paths, backslashes, or dot segments. */
+function relativePath(value: unknown): value is string {
+  return typeof value === "string" && !value.startsWith("/") && !value.includes("\\") && value.split("/").every(part => part && part !== "." && part !== "..");
+}
+export function titleCase(name: string): string {
+  return name.split("-").map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+
+function parseProjects(value: unknown, setting: string): ScreenshotProject[] {
+  const entries = Object.entries(object(value, setting));
+  if (!entries.length) fail(setting);
+  return entries.map(([name, entry]) => {
+    if (!NAME.test(name)) fail(`${setting}.${name}`);
+    if (text(entry)) return { name, label: entry, dir: name, frame: null };
+    const project = object(entry, `${setting}.${name}`, ["label", "dir", "frame"]);
+    if (project.label !== undefined && !text(project.label)) fail(`${setting}.${name}.label`);
+    if (project.dir !== undefined && (typeof project.dir !== "string" || !NAME.test(project.dir))) fail(`${setting}.${name}.dir`);
+    if (project.frame !== undefined && !FRAMES.includes(project.frame as Frame)) fail(`${setting}.${name}.frame`);
+    return { name, label: (project.label as string | undefined) ?? titleCase(name), dir: (project.dir as string | undefined) ?? name, frame: (project.frame as Frame | undefined) ?? null };
+  });
+}
+
+function parseScreens(value: unknown, setting: string): ScreenshotScreen[] {
+  if (!Array.isArray(value) || !value.length) fail(setting);
+  const screens = value.map((entry, index): ScreenshotScreen => {
+    if (typeof entry === "string") {
+      if (!NAME.test(entry)) fail(`${setting}[${index}]`);
+      return { name: entry, label: titleCase(entry), alt: null };
+    }
+    const screen = object(entry, `${setting}[${index}]`, ["name", "label", "alt"]);
+    if (typeof screen.name !== "string" || !NAME.test(screen.name)) fail(`${setting}[${index}].name`);
+    if (screen.label !== undefined && !text(screen.label)) fail(`${setting}[${index}].label`);
+    if (screen.alt !== undefined && !text(screen.alt)) fail(`${setting}[${index}].alt`);
+    return { name: screen.name, label: (screen.label as string | undefined) ?? titleCase(screen.name), alt: (screen.alt as string | undefined) ?? null };
+  });
+  const repeated = screens.find((screen, index) => screens.findIndex(other => other.name === screen.name) !== index);
+  if (repeated) throw new Error(`${setting} lists '${repeated.name}' more than once.`);
+  return screens;
+}
+
+export function parseScreenshots(value: unknown): ScreenshotsConfig {
+  const input = object(value, "screenshots", ["source", "targets"]);
+  if (input.source !== undefined && !relativePath(input.source)) fail("screenshots.source");
+  const result: ScreenshotsConfig = { source: (input.source as string | undefined) ?? SCREENSHOTS_DEFAULTS.source, targets: {} };
+  for (const [name, entry] of Object.entries(object(input.targets ?? {}, "screenshots.targets"))) {
+    const setting = `screenshots.targets.${name}`;
+    if (!TARGET.test(name)) fail(setting);
+    const target = object(entry, setting, ["dir", "urlPrefix", "projects", "themes", "screens"]);
+    if (target.dir !== undefined && !relativePath(target.dir)) fail(`${setting}.dir`);
+    // A URL path or absolute URL that image names are appended to; no characters that need escaping in HTML or CSS.
+    if (typeof target.urlPrefix !== "string" || !/^(?:\/|https:\/\/[^/\s]+\/)[^\s"'<>\\()]*$/.test(target.urlPrefix) || !target.urlPrefix.endsWith("/")) fail(`${setting}.urlPrefix`);
+    const projects = parseProjects(target.projects, `${setting}.projects`);
+    const dirs = projects.map(project => project.dir);
+    const shared = dirs.find((dir, index) => dirs.indexOf(dir) !== index);
+    if (shared) throw new Error(`${setting}.projects read capture directory '${shared}' more than once.`);
+    const themes = target.themes ?? ["light", "dark"];
+    if (!Array.isArray(themes) || !themes.length || themes.some(theme => typeof theme !== "string" || !NAME.test(theme)) || new Set(themes).size !== themes.length) fail(`${setting}.themes`);
+    result.targets[name] = { dir: (target.dir as string | undefined) ?? null, urlPrefix: target.urlPrefix, projects, themes: themes as string[], screens: parseScreens(target.screens, `${setting}.screens`) };
+  }
+  return result;
+}