agents-pod 0.0.0-stage → 0.2.0

package/src/liveness.ts

@@ -0,0 +1,191 @@
+import { execFile } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { uptime } from "node:os";
+import { join } from "node:path";
+import { podDir } from "./paths.ts";
+import type { PodRecord } from "./registry.ts";
+import type { DocFacts } from "./workspace.ts";
+
+/** The heartbeat staleness line: 3 minutes — six missed 30-second beats (ADR 0017). */
+export const HEARTBEAT_STALE_MS = 180_000;
+
+/** The wedged escalation line: 10 stale minutes with a live wrapper (ADR 0017). */
+export const WEDGED_ESCALATE_MS = 600_000;
+
+/** ADR 0017's four quadrants; `status` reports one per pod. */
+export type Liveness = "healthy" | "lost" | "wedged-pending" | "wedged";
+
+/** Why a pod is `lost`; the detail text and the signal decision follow from it. */
+export type LostCause = "ghost" | "reboot" | "wrapper-gone";
+
+/**
+ * The wrapper's identity record (ADR 0003): who runs this wake-up, probeable.
+ * The spawn-time facts (ADR 0020) — `pidStart`, the process start time as `ps`
+ * renders it, and `bootTime`, the wall-clock boot moment — are written once at
+ * spawn. A record without them cannot be trusted for a signal: absence is a
+ * mismatch, never a wildcard.
+ */
+export interface WrapperRecord {
+  pid: number;
+  pgid: number;
+  wakeup: number;
+  startedAt: number;
+  pidStart?: string;
+  bootTime?: number;
+  /**
+   * The document store's mtime+size at wake-up start (ADR 0019): the pass
+   * compares this baseline against the present to judge progress. Absent means
+   * no baseline — never "unchanged".
+   */
+  docs?: Record<string, DocFacts>;
+}
+
+/**
+ * The machine's identity (ADR 0020): the wall-clock moment of boot. Two
+ * readings differ by `os.uptime`'s resolution (whole seconds on macOS), so a
+ * real reboot — which moves the value by the whole previous uptime — is the
+ * only thing that exceeds the tolerance.
+ */
+export const BOOT_TIME_TOLERANCE_MS = 3_000;
+
+export function currentBootTime(): number {
+  return Date.now() - uptime() * 1000;
+}
+
+export function bootTimeMatches(recorded: number | undefined): boolean {
+  return (
+    typeof recorded === "number" &&
+    Math.abs(currentBootTime() - recorded) <= BOOT_TIME_TOLERANCE_MS
+  );
+}
+
+/**
+ * `ps -o lstart=` for a pid: one call answers both questions ADR 0020 asks of
+ * a kill — is the pid live, and when did it start. `LC_ALL=C` keeps the
+ * rendering identical to the string the wrapper recorded. Undefined means the
+ * pid is gone (or unreadable), which is never a failure in itself.
+ */
+export function psStart(pid: number): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    execFile(
+      "ps",
+      ["-o", "lstart=", "-p", String(pid)],
+      { env: { ...process.env, LC_ALL: "C" } },
+      (error, stdout) => {
+        if (error) {
+          resolve(undefined);
+          return;
+        }
+        const start = stdout.trim();
+        resolve(start.length > 0 ? start : undefined);
+      },
+    );
+  });
+}
+
+/**
+ * ADR 0020's three-way verification of a recorded wrapper: the boot time is
+ * this boot's, the pid is live, and its start time is the recorded one. Any
+ * mismatch means the recorded process is long gone — a pid is just a number
+ * after a reboot.
+ */
+export async function verifyProcess(record: WrapperRecord): Promise<boolean> {
+  if (!bootTimeMatches(record.bootTime)) return false;
+  const start = await psStart(record.pid);
+  if (start === undefined || typeof record.pidStart !== "string") return false;
+  return start === record.pidStart.trim();
+}
+
+/**
+ * ADR 0020's reaping gate: the recorded wrapper is verifiably dead — this is
+ * not a reboot, and no process answers at its pid — so its process group may
+ * be reaped. A live pid fails this check: that case is the wedged path, which
+ * needs `verifyProcess`.
+ */
+export async function wrapperVerifiablyDead(record: WrapperRecord): Promise<boolean> {
+  if (!bootTimeMatches(record.bootTime)) return false;
+  return (await psStart(record.pid)) === undefined;
+}
+
+export function wrapperJsonPath(project: string, podId: string): string {
+  return join(podDir(project, podId), "wrapper.json");
+}
+
+export async function readWrapperRecord(
+  pod: Pick<PodRecord, "id" | "project">,
+): Promise<WrapperRecord | undefined> {
+  const body = await readFile(wrapperJsonPath(pod.project, pod.id), "utf8").catch(
+    () => undefined,
+  );
+  if (body === undefined) return undefined;
+  try {
+    return JSON.parse(body) as WrapperRecord;
+  } catch {
+    return undefined;
+  }
+}
+
+/** A dead pid is the ordinary crash; EPERM still means alive. */
+export function pidDead(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ESRCH";
+  }
+}
+
+async function heartbeatAgeMs(
+  pod: Pick<PodRecord, "id" | "project">,
+): Promise<number | undefined> {
+  const info = await stat(join(podDir(pod.project, pod.id), "heartbeat")).catch(
+    () => undefined,
+  );
+  return info === undefined ? undefined : Date.now() - info.mtimeMs;
+}
+
+export interface LivenessFacts {
+  quadrant: Liveness;
+  wrapper?: WrapperRecord;
+  beatAgeMs?: number;
+  /** Only for `lost`: which fact condemned the wake-up. */
+  lostCause?: LostCause;
+}
+
+/**
+ * The three-way rule (ADR 0017), from owned facts only — pid plus heartbeat
+ * age, never elapsed run time:
+ * 1. pid live + beat fresh → healthy
+ * 2. pid dead + beat stale → lost
+ * 3. pid live + beat stale → wedged, with the ten-minute escalation shown as
+ *    wedged-pending until the two-pass kill exists
+ * A record that says active with no wrapper identity at all is a ghost
+ * (ADR 0002). Anything not active has nothing running: healthy.
+ *
+ * Identity comes first (ADR 0020): a boot time that is not this boot's means
+ * the machine restarted since the wake-up began, so the pod is lost at once
+ * and no recorded pid is probed or trusted — after a reboot those numbers
+ * belong to someone else.
+ */
+export async function livenessFacts(
+  pod: Pick<PodRecord, "id" | "project" | "state">,
+): Promise<LivenessFacts> {
+  if (pod.state !== "active") return { quadrant: "healthy" };
+  const wrapper = await readWrapperRecord(pod);
+  const beatAgeMs = await heartbeatAgeMs(pod);
+  if (wrapper === undefined) return { quadrant: "lost", beatAgeMs, lostCause: "ghost" };
+  if (!bootTimeMatches(wrapper.bootTime)) {
+    return { quadrant: "lost", wrapper, beatAgeMs, lostCause: "reboot" };
+  }
+  if (pidDead(wrapper.pid)) {
+    if (beatAgeMs !== undefined && beatAgeMs >= HEARTBEAT_STALE_MS) {
+      return { quadrant: "lost", wrapper, beatAgeMs, lostCause: "wrapper-gone" };
+    }
+    return { quadrant: "wedged", wrapper, beatAgeMs };
+  }
+  if (beatAgeMs === undefined || beatAgeMs >= WEDGED_ESCALATE_MS) {
+    return { quadrant: "wedged-pending", wrapper, beatAgeMs };
+  }
+  if (beatAgeMs >= HEARTBEAT_STALE_MS) return { quadrant: "wedged", wrapper, beatAgeMs };
+  return { quadrant: "healthy", wrapper, beatAgeMs };
+}

package/src/locks.ts

@@ -0,0 +1,74 @@
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+/**
+ * The advisory lock primitives (ADR 0018): `wx` is the only race-free acquire
+ * — the kernel's exclusive create is the arbitration — and a lock is released
+ * only by its owner, so a stolen (inert zombie) pass cannot delete the file
+ * of the pass that stole it.
+ */
+export interface LockRecord {
+  pid: number;
+  startedAt: number;
+}
+
+export async function acquireLock(file: string, record: LockRecord): Promise<boolean> {
+  await mkdir(dirname(file), { recursive: true });
+  try {
+    await writeFile(file, `${JSON.stringify(record)}\n`, { flag: "wx", mode: 0o600 });
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+    throw error;
+  }
+}
+
+/** A lock whose contents cannot be parsed is `undefined`, never a crash. */
+export async function readLock(file: string): Promise<LockRecord | undefined> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(file, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return undefined;
+    const { pid, startedAt } = parsed as Partial<LockRecord>;
+    if (typeof pid !== "number" || typeof startedAt !== "number") return undefined;
+    return { pid, startedAt };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Idempotent and owner-checked: safe in a `finally` (ADR 0018). */
+export async function releaseLock(file: string): Promise<void> {
+  const held = await readLock(file);
+  if (held?.pid !== process.pid) return;
+  await unlink(file).catch(() => undefined);
+}
+
+/**
+ * ADR 0017's registry-lock shape: a 5-second budget, 25 ms fixed retries, two
+ * rounds. Two lost budgets are a wedged holder, not a slow one, so the lock is
+ * broken once — the same TTL reasoning the pass lock applies (ADR 0018); pid
+ * liveness is never the judge.
+ */
+const RETRY_BUDGET_MS = 5_000;
+const RETRY_INTERVAL_MS = 25;
+const RETRY_ROUNDS = 2;
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function acquireWithRetry(
+  file: string,
+  record: LockRecord,
+): Promise<boolean> {
+  for (let round = 0; round < RETRY_ROUNDS; round += 1) {
+    const deadline = Date.now() + RETRY_BUDGET_MS;
+    for (;;) {
+      if (await acquireLock(file, record)) return true;
+      if (Date.now() >= deadline) break;
+      await sleep(RETRY_INTERVAL_MS);
+    }
+  }
+  await unlink(file).catch(() => undefined);
+  return acquireLock(file, record);
+}

package/src/notify/config.ts

@@ -0,0 +1,125 @@
+import { readFile } from "node:fs/promises";
+import { notifyConfigFile } from "../paths.ts";
+import type {
+  EmailChannel,
+  NotificationChannel,
+  NotificationsConfig,
+  NotifyLevel,
+  SystemChannel,
+  WebhookChannel,
+} from "./types.ts";
+
+/**
+ * The default is `always`, not agents-cron's `error` (ADR 0021): work
+ * measured in days makes completion the product, so it is announced too.
+ */
+export const DEFAULT_NOTIFY_LEVEL: NotifyLevel = "always";
+
+/** Where config warnings go: reconcile routes them to cron.log (ADR 0021). */
+export type ConfigWarning = (message: string) => void;
+
+const stderrWarning: ConfigWarning = (message) => {
+  process.stderr.write(`[agents-pod] ${message}\n`);
+};
+
+/**
+ * Reads the store's `config.json` (ADR 0021). The file is optional and
+ * user-authored: missing means "no channels", and anything malformed degrades
+ * to defaults with a warning — a bad config must never take down a pass.
+ */
+export async function loadNotifyConfig(
+  file: string = notifyConfigFile(),
+  warn: ConfigWarning = stderrWarning,
+): Promise<NotificationsConfig> {
+  let raw: string;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return { on: DEFAULT_NOTIFY_LEVEL, channels: [] };
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    return normalize(parsed, file, warn);
+  } catch (err) {
+    warn(
+      `${file}: not valid JSON (${err instanceof Error ? err.message : String(err)}); using notification defaults`,
+    );
+    return { on: DEFAULT_NOTIFY_LEVEL, channels: [] };
+  }
+}
+
+function normalize(
+  parsed: Record<string, unknown>,
+  file: string,
+  warn: ConfigWarning,
+): NotificationsConfig {
+  const notifications = (parsed.notifications ?? {}) as Record<string, unknown>;
+  const on = isNotifyLevel(notifications.on) ? notifications.on : DEFAULT_NOTIFY_LEVEL;
+  if (notifications.on !== undefined && !isNotifyLevel(notifications.on)) {
+    warn(
+      `${file}: notifications.on "${String(notifications.on)}" is not one of always|error|never; using "${on}"`,
+    );
+  }
+
+  const channels: NotificationChannel[] = [];
+  for (const entry of Array.isArray(notifications.channels) ? notifications.channels : []) {
+    const channel = asChannel(entry);
+    if (channel) channels.push(channel);
+    else warn(`${file}: dropping invalid notification channel ${JSON.stringify(entry)}`);
+  }
+  return { on, channels };
+}
+
+function asChannel(entry: unknown): NotificationChannel | undefined {
+  if (typeof entry !== "object" || entry === null) return undefined;
+  const c = entry as Record<string, unknown>;
+  if (typeof c.id !== "string" || !c.id.trim()) return undefined;
+
+  if (c.type === "webhook") {
+    if (typeof c.url !== "string" || !/^https?:\/\//.test(c.url)) return undefined;
+    const headers =
+      c.headers && typeof c.headers === "object" && Object.values(c.headers).every((v) => typeof v === "string")
+        ? (c.headers as Record<string, string>)
+        : undefined;
+    const format = c.format === "text" || c.format === "feishu" ? c.format : "json";
+    return {
+      id: c.id,
+      type: "webhook",
+      url: c.url,
+      ...(headers ? { headers } : {}),
+      ...(format !== "json" ? { format } : {}),
+    } satisfies WebhookChannel;
+  }
+
+  if (c.type === "email") {
+    if (typeof c.host !== "string" || !c.host) return undefined;
+    if (typeof c.from !== "string" || !c.from) return undefined;
+    if (typeof c.to !== "string" || !c.to) return undefined;
+    const port = typeof c.port === "number" ? c.port : 465;
+    const channel: EmailChannel = {
+      id: c.id,
+      type: "email",
+      host: c.host,
+      port,
+      from: c.from,
+      to: c.to,
+      ...(typeof c.secure === "boolean" ? { secure: c.secure } : { secure: port === 465 }),
+      ...(typeof c.user === "string" && c.user ? { user: c.user } : {}),
+      ...(typeof c.passwordEnv === "string" && c.passwordEnv ? { passwordEnv: c.passwordEnv } : {}),
+      ...(typeof c.subjectPrefix === "string" && c.subjectPrefix ? { subjectPrefix: c.subjectPrefix } : {}),
+    };
+    return channel;
+  }
+
+  if (c.type === "system") {
+    if (typeof c.sound !== "string" || !c.sound) return { id: c.id, type: "system" } satisfies SystemChannel;
+    return { id: c.id, type: "system", sound: c.sound } satisfies SystemChannel;
+  }
+
+  return undefined;
+}
+
+function isNotifyLevel(value: unknown): value is NotifyLevel {
+  return value === "always" || value === "error" || value === "never";
+}

package/src/notify/dispatch.ts

@@ -0,0 +1,63 @@
+import { emailNotifier } from "./email.ts";
+import { systemNotifier } from "./system.ts";
+import { webhookNotifier } from "./webhook.ts";
+import type {
+  NotificationChannel,
+  NotificationEvent,
+  NotificationsConfig,
+  Notifier,
+  NotifyLevel,
+  PodNotification,
+} from "./types.ts";
+
+/**
+ * Whether a pod moment warrants a notification at this level (ADR 0021):
+ * `error` is park-only, `always` is park + done, `never` is silent. There is
+ * no per-outcome inventory — failed, lost, more, and cancelled never reach
+ * this function at all.
+ */
+export function shouldNotify(level: NotifyLevel, event: NotificationEvent): boolean {
+  if (level === "never") return false;
+  if (level === "error") return event === "park";
+  return true;
+}
+
+/** Resolves configured channels into notifiers. */
+export function notifiersFor(config: NotificationsConfig): Notifier[] {
+  return config.channels.map(notifierFor);
+}
+
+function notifierFor(channel: NotificationChannel): Notifier {
+  if (channel.type === "webhook") return webhookNotifier(channel);
+  if (channel.type === "email") return emailNotifier(channel);
+  return systemNotifier(channel);
+}
+
+/**
+ * Offers one pod moment to every configured channel, best effort: the
+ * channels run in parallel inside their ten-second budgets, and every failure
+ * becomes a note for cron.log instead of a throw — a broken webhook must never
+ * break the pass, and a failed delivery is logged, never retried (ADR 0021).
+ */
+export async function dispatchNotification(
+  config: NotificationsConfig,
+  notification: PodNotification,
+): Promise<string[]> {
+  if (config.channels.length === 0) {
+    // Unconfigured is a valid state, not an error: the moment is consumed and
+    // the log says where the announcement would have gone.
+    return [
+      `no notification channels configured; ${notification.event} of ${notification.podId} not announced (add channels to config.json)`,
+    ];
+  }
+
+  const notifiers = notifiersFor(config);
+  const settled = await Promise.allSettled(
+    notifiers.map((notifier) => notifier.send(notification)),
+  );
+  return settled.flatMap((result, index) => {
+    if (result.status === "fulfilled") return [];
+    const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+    return [`channel "${notifiers[index]!.id}" failed for ${notification.podId}: ${reason}`];
+  });
+}

package/src/notify/email.ts

@@ -0,0 +1,72 @@
+import { bodyOf, subjectOf } from "./format.ts";
+import type { EmailChannel, Notifier, PodNotification } from "./types.ts";
+
+/** What nodemailer's transport needs; injectable so tests never touch SMTP. */
+export type MailTransport = {
+  sendMail(options: {
+    from: string;
+    to: string;
+    subject: string;
+    text: string;
+  }): Promise<unknown>;
+};
+
+export type TransportFactory = (channel: EmailChannel, password?: string) => Promise<MailTransport>;
+
+type NodemailerModule = {
+  createTransport(options: {
+    host: string;
+    port: number;
+    secure: boolean;
+    auth?: { user: string; pass: string };
+  }): MailTransport;
+};
+
+/**
+ * Builds the real transport by lazily importing nodemailer, which is an
+ * optional dependency: only users who configure an email channel pay for it,
+ * and everyone else keeps the zero-SMTP footprint. The specifier is a variable
+ * so typecheck never requires the package to be installed.
+ */
+const nodemailerTransport: TransportFactory = async (channel, password) => {
+  const specifier = "nodemailer";
+  let nodemailer: NodemailerModule;
+  try {
+    nodemailer = (await import(specifier)) as NodemailerModule;
+  } catch {
+    throw new Error(
+      `email channel "${channel.id}" needs the optional nodemailer package: run "npm install nodemailer" (or reinstall agents-pod)`,
+    );
+  }
+  return nodemailer.createTransport({
+    host: channel.host,
+    port: channel.port ?? 465,
+    secure: channel.secure ?? (channel.port ?? 465) === 465,
+    ...(channel.user ? { auth: { user: channel.user, pass: password ?? "" } } : {}),
+  });
+};
+
+export function emailNotifier(
+  channel: EmailChannel,
+  env: NodeJS.ProcessEnv = process.env,
+  createTransport: TransportFactory = nodemailerTransport,
+): Notifier {
+  return {
+    id: channel.id,
+    async send(n: PodNotification): Promise<void> {
+      const password = env[channel.passwordEnv ?? "AGENTS_POD_SMTP_PASSWORD"];
+      if (channel.user && !password) {
+        throw new Error(
+          `email channel "${channel.id}" authenticates as ${channel.user}, but ${channel.passwordEnv ?? "AGENTS_POD_SMTP_PASSWORD"} is not set`,
+        );
+      }
+      const transport = await createTransport(channel, password);
+      await transport.sendMail({
+        from: channel.from,
+        to: channel.to,
+        subject: `${channel.subjectPrefix ?? "[agents-pod] "}${subjectOf(n)}`,
+        text: bodyOf(n),
+      });
+    },
+  };
+}

package/src/notify/format.ts

@@ -0,0 +1,42 @@
+import type { NotificationEvent, PodNotification } from "./types.ts";
+
+const ICONS: Record<NotificationEvent, string> = {
+  park: "■",
+  done: "✓",
+};
+
+/** One-line human summary, used as the email subject and the text body's head. */
+export function subjectOf(n: PodNotification): string {
+  return `${ICONS[n.event]} ${n.event}: ${n.goal}`;
+}
+
+/** The one pointer line: enough to decide whether to look, fix, or re-wake. */
+export function pointerOf(n: PodNotification): string {
+  return `agents-pod status ${n.podId}  ·  agents-pod logs ${n.podId}`;
+}
+
+/** Plain-text body: the verdict a human needs, and nothing else. */
+export function bodyOf(n: PodNotification): string {
+  if (n.event === "done") {
+    return [
+      `pod:     ${n.podId}`,
+      `goal:    ${n.goal}`,
+      `handoff: ${n.handoffStatus ?? "status: done"}`,
+      "",
+      pointerOf(n),
+    ].join("\n");
+  }
+
+  return [
+    `pod:     ${n.podId}`,
+    `goal:    ${n.goal}`,
+    ...(n.reason ? [`reason:  ${n.reason}`] : []),
+    `consecutive failures: ${n.consecutiveFailures ?? 0}`,
+    ...(n.failures ?? []).map(
+      (failure) =>
+        `- wake-up ${failure.n} ${failure.outcome}${failure.detail ? `: ${failure.detail}` : ""}`,
+    ),
+    "",
+    pointerOf(n),
+  ].join("\n");
+}

package/src/notify/system.ts

@@ -0,0 +1,79 @@
+import { spawn } from "node:child_process";
+import type { Notifier, PodNotification, SystemChannel } from "./types.ts";
+
+/** Same delivery budget as a webhook: a hung helper must not stall a pass (ADR 0021). */
+const TIMEOUT_MS = 10_000;
+
+/** Notifications carry a goal line; never let it grow past a banner's size. */
+const MAX_DETAIL = 500;
+
+/** Injectable process runner so tests never pop real notifications. */
+export type CommandRunner = (command: string, args: string[]) => Promise<{ status: number | null; stderr: string }>;
+
+const spawnRunner: CommandRunner = (command, args) =>
+  new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ["ignore", "ignore", "pipe"] });
+    const timer = setTimeout(() => child.kill("SIGKILL"), TIMEOUT_MS);
+    let stderr = "";
+    child.stderr?.on("data", (chunk) => (stderr += chunk));
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on("close", (status) => {
+      clearTimeout(timer);
+      resolve({ status, stderr });
+    });
+  });
+
+/**
+ * Announces a pod moment on the desktop: macOS Notification Center via
+ * osascript, Linux via notify-send. The goal is user text, so it is
+ * length-capped and AppleScript-escaped before it ever reaches a script.
+ */
+export function systemNotifier(
+  channel: SystemChannel,
+  platform: NodeJS.Platform = process.platform,
+  run: CommandRunner = spawnRunner,
+): Notifier {
+  return {
+    id: channel.id,
+    async send(n: PodNotification): Promise<void> {
+      const title = `agents-pod ${n.event}`;
+      const detail = cap(n.goal);
+      if (platform === "darwin") {
+        const result = await run("osascript", [
+          "-e",
+          [
+            `display notification "${escape(detail)}"`,
+            `with title "${escape(title)}"`,
+            `subtitle "${escape(n.podId)}"`,
+            ...(channel.sound ? [`sound name "${escape(channel.sound)}"`] : []),
+          ].join(" "),
+        ]);
+        requireSuccess("osascript", result);
+        return;
+      }
+      if (platform === "linux") {
+        const result = await run("notify-send", [title, detail]);
+        requireSuccess("notify-send", result);
+        return;
+      }
+      throw new Error(`system channel "${channel.id}" supports macOS and Linux, not ${platform}`);
+    },
+  };
+}
+
+/** A helper that exited non-zero (or was killed) failed — surface its exit status and stderr. */
+function requireSuccess(command: string, result: { status: number | null; stderr: string }): void {
+  if (result.status !== 0) throw new Error(`${command} exited ${result.status}: ${result.stderr.trim()}`);
+}
+
+/** AppleScript string literal: only backslash and double quote are special. */
+function escape(text: string): string {
+  return text.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function cap(text: string): string {
+  return text.length > MAX_DETAIL ? `${text.slice(0, MAX_DETAIL)}…` : text;
+}