harnery 0.46.1 → 0.47.0

package/src/lib/computer/host.ts

@@ -0,0 +1,87 @@
+/**
+ * Host detection for `harn computer` (ADR 0228).
+ *
+ * Decides whose desktop this process can drive and where the state shared by
+ * every caller of that desktop lives (`%LOCALAPPDATA%\harnery`). Native
+ * Windows and WSL2 both drive the Windows desktop; everything else is
+ * unsupported for now.
+ *
+ * Internal module: not exported from package.json.
+ */
+import { win32 } from "node:path";
+import { isWSL } from "../browser/launch-args.ts";
+import { windowsLocalAppData, windowsPathToWsl } from "../browser/windows-chrome.ts";
+import type { HostInfo } from "./types.ts";
+
+export interface HostDeps {
+  /** Defaults to `process.platform`. */
+  platform?: NodeJS.Platform;
+  /** Defaults to `process.env`. Native Windows reads `LOCALAPPDATA` from it. */
+  env?: NodeJS.ProcessEnv;
+  /** Defaults to the shared WSL probe. Consulted only on Linux. */
+  isWsl?: () => boolean;
+  /** `%LOCALAPPDATA%` as a Windows path, read through interop. WSL only. */
+  localAppData?: () => string | undefined;
+}
+
+const MACOS_REASON =
+  "macOS is not yet supported: its desktop driver needs an app bundle and accessibility and screen-recording grants (ADR 0228).";
+const LINUX_REASON =
+  "Linux desktops are not yet supported; computer use drives a Windows desktop from native Windows or WSL2 (ADR 0228).";
+
+let cached: HostInfo | undefined;
+
+/**
+ * Resolve the host. The default (no deps) result is cached for the life of
+ * the process; injected deps always recompute.
+ */
+export function detectHost(deps?: HostDeps): HostInfo {
+  if (!deps && cached) return cached;
+  const result = resolveHost(deps ?? {});
+  if (!deps) cached = result;
+  return result;
+}
+
+/** Forget the cached default result (tests only). */
+export function resetHostCache(): void {
+  cached = undefined;
+}
+
+function resolveHost(deps: HostDeps): HostInfo {
+  const platform = deps.platform ?? process.platform;
+  const env = deps.env ?? process.env;
+  if (platform === "win32") {
+    const localAppData = env.LOCALAPPDATA?.trim();
+    if (!localAppData)
+      return {
+        kind: "unsupported",
+        reason: "LOCALAPPDATA is not set, so the shared desktop state directory is unknown.",
+      };
+    return { kind: "windows", desktopStateDir: win32.join(localAppData, "harnery") };
+  }
+  if (platform === "linux" && (deps.isWsl ?? isWSL)()) {
+    const localAppData = (deps.localAppData ?? windowsLocalAppData)();
+    if (!localAppData)
+      return {
+        kind: "unsupported",
+        reason:
+          "Running under WSL, but %LOCALAPPDATA% could not be read through Windows interop (cmd.exe). Check that interop is enabled.",
+      };
+    let mounted: string;
+    try {
+      mounted = windowsPathToWsl(localAppData);
+    } catch {
+      return {
+        kind: "unsupported",
+        reason: `Running under WSL, but %LOCALAPPDATA% is not a drive-letter path: ${localAppData}`,
+      };
+    }
+    return { kind: "wsl", desktopStateDir: `${mounted}/harnery` };
+  }
+  if (platform === "darwin") return { kind: "unsupported", reason: MACOS_REASON };
+  if (platform === "linux") return { kind: "unsupported", reason: LINUX_REASON };
+  return {
+    kind: "unsupported",
+    reason: `Platform ${platform} is not supported for computer use (ADR 0228).`,
+  };
+}

package/src/lib/computer/lease.ts

@@ -0,0 +1,299 @@
+/**
+ * Desktop lease for `harn computer` (ADR 0228).
+ *
+ * One JSON file per desktop records which agent may drive it. Callers are
+ * short-lived CLI invocations from WSL distros and native Windows shells that
+ * share the file through `/mnt/<drive>` (drvfs) or the native path, so this
+ * module relies on nothing that breaks across that boundary:
+ *
+ * - No flock and no pid liveness. Owner identity is `LeaseOwner.id`; a lease
+ *   ends when its owner releases it or when it sits idle past `expires_at`.
+ * - The read-modify-write critical section is an atomic `mkdir` of
+ *   `<dir>/lease.lock`. The holder writes `owner.json` ({pid, at, token}) into
+ *   it and keeps it for milliseconds. A lock older than 10 seconds belongs to
+ *   a crashed holder and is broken.
+ * - Lease writes go to a temporary file in the same directory and are renamed
+ *   over the target, so a reader never sees a partial record.
+ *
+ * Generation rule: every acquisition of a free or expired lease increments
+ * `generation`, including an owner re-taking its own lease after it expired.
+ * A refresh of an unexpired lease by the same owner keeps the generation.
+ *
+ * Internal module: not exported from package.json.
+ */
+import { randomUUID } from "node:crypto";
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type {
+  DesktopLease,
+  LeaseAcquireResult,
+  LeaseApi,
+  LeaseOptions,
+  LeaseOwner,
+} from "./types.ts";
+
+/** Idle expiry when `LeaseOptions.idleMs` is omitted. */
+export const DEFAULT_LEASE_IDLE_MS = 120_000;
+const DEFAULT_POLL_MS = 500;
+const LEASE_FILE = "desktop-lease.json";
+const LOCK_DIR = "lease.lock";
+const LOCK_OWNER_FILE = "owner.json";
+/** A critical-section lock older than this belongs to a crashed holder. */
+const LOCK_STALE_MS = 10_000;
+/** Give up on the critical section after this long (stale break happens first). */
+const LOCK_TIMEOUT_MS = 15_000;
+const LOCK_RETRY_MS = 10;
+
+/** Directory holding the lease file for a desktop state dir. */
+export function leaseDir(desktopStateDir: string): string {
+  return join(desktopStateDir, "computer");
+}
+
+function leaseFile(dir: string): string {
+  return join(dir, LEASE_FILE);
+}
+
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function errCode(error: unknown): string | undefined {
+  return (error as NodeJS.ErrnoException | undefined)?.code;
+}
+
+/** Parse a lease record; anything malformed counts as no lease. */
+function parseLease(text: string): DesktopLease | null {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!value || typeof value !== "object") return null;
+  const lease = value as Partial<DesktopLease>;
+  if (
+    lease.schema !== 1 ||
+    typeof lease.owner_id !== "string" ||
+    typeof lease.owner_label !== "string" ||
+    typeof lease.generation !== "number" ||
+    !Number.isFinite(lease.generation) ||
+    typeof lease.acquired_at !== "string" ||
+    typeof lease.refreshed_at !== "string" ||
+    typeof lease.expires_at !== "string" ||
+    Number.isNaN(Date.parse(lease.expires_at))
+  ) {
+    return null;
+  }
+  return lease as DesktopLease;
+}
+
+/** The lease record on disk, expired or not; null when missing or corrupt. */
+function readRaw(dir: string): DesktopLease | null {
+  try {
+    return parseLease(readFileSync(leaseFile(dir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function isExpired(lease: DesktopLease, nowMs: number): boolean {
+  return nowMs >= Date.parse(lease.expires_at);
+}
+
+function writeLease(dir: string, lease: DesktopLease): void {
+  const tmp = join(dir, `${LEASE_FILE}.${process.pid}.${randomUUID()}.tmp`);
+  writeFileSync(tmp, `${JSON.stringify(lease, null, 2)}\n`);
+  try {
+    renameSync(tmp, leaseFile(dir));
+  } catch (error) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      // best effort
+    }
+    throw error;
+  }
+}
+
+/** Age of a lock dir: owner.json `at`, else the directory mtime. */
+function lockAgeMs(lockDir: string): number | undefined {
+  try {
+    const owner = JSON.parse(readFileSync(join(lockDir, LOCK_OWNER_FILE), "utf8")) as {
+      at?: unknown;
+    };
+    const at = typeof owner.at === "string" ? Date.parse(owner.at) : Number.NaN;
+    if (!Number.isNaN(at)) return Date.now() - at;
+  } catch {
+    // owner.json not written yet or unreadable: fall back to the dir itself
+  }
+  try {
+    return Date.now() - statSync(lockDir).mtimeMs;
+  } catch {
+    return undefined; // lock vanished
+  }
+}
+
+/** Break a stale lock. Rename first so two breakers cannot both win. */
+function breakLock(lockDir: string): void {
+  const grave = `${lockDir}.stale.${process.pid}.${randomUUID()}`;
+  try {
+    renameSync(lockDir, grave);
+  } catch {
+    return; // someone else broke or released it
+  }
+  rmSync(grave, { recursive: true, force: true });
+}
+
+/**
+ * Run `fn` while holding the critical-section lock in `dir` (which must
+ * exist). Synchronous: the section is a few file operations, and release()
+ * is synchronous in the contract.
+ */
+function withLock<T>(dir: string, fn: () => T): T {
+  const lockDir = join(dir, LOCK_DIR);
+  const token = randomUUID();
+  const started = Date.now();
+  for (;;) {
+    try {
+      mkdirSync(lockDir);
+      break;
+    } catch (error) {
+      if (errCode(error) !== "EEXIST") throw error;
+    }
+    const age = lockAgeMs(lockDir);
+    if (age !== undefined && age > LOCK_STALE_MS) {
+      breakLock(lockDir);
+      continue;
+    }
+    if (Date.now() - started > LOCK_TIMEOUT_MS) {
+      throw new Error(`desktop lease: timed out waiting for ${lockDir}`);
+    }
+    sleepSync(LOCK_RETRY_MS);
+  }
+  try {
+    writeFileSync(
+      join(lockDir, LOCK_OWNER_FILE),
+      JSON.stringify({ pid: process.pid, at: new Date().toISOString(), token }),
+    );
+  } catch {
+    // The mkdir already gave us the lock; owner.json only aids stale detection.
+  }
+  try {
+    return fn();
+  } finally {
+    releaseLock(lockDir, token);
+  }
+}
+
+/** Remove the lock only if it is still ours (a slow holder may have been broken). */
+function releaseLock(lockDir: string, token: string): void {
+  try {
+    const owner = JSON.parse(readFileSync(join(lockDir, LOCK_OWNER_FILE), "utf8")) as {
+      token?: unknown;
+    };
+    if (owner.token !== token) return;
+  } catch (error) {
+    if (errCode(error) !== "ENOENT") return; // unreadable owner.json: leave it for stale breaking
+    // owner.json missing: our write failed or the lock is gone; fall through
+  }
+  rmSync(lockDir, { recursive: true, force: true });
+}
+
+type TryResult =
+  | { ok: true; lease: DesktopLease; fresh: boolean }
+  | { ok: false; holder: DesktopLease };
+
+function tryAcquire(owner: LeaseOwner, dir: string, nowMs: number, idleMs: number): TryResult {
+  return withLock(dir, () => {
+    const current = readRaw(dir);
+    const nowIso = new Date(nowMs).toISOString();
+    const expiresIso = new Date(nowMs + idleMs).toISOString();
+    if (current && !isExpired(current, nowMs)) {
+      if (current.owner_id !== owner.id) return { ok: false, holder: current };
+      const refreshed: DesktopLease = { ...current, refreshed_at: nowIso, expires_at: expiresIso };
+      writeLease(dir, refreshed);
+      return { ok: true, lease: refreshed, fresh: false };
+    }
+    const lease: DesktopLease = {
+      schema: 1,
+      owner_id: owner.id,
+      owner_label: owner.label,
+      ...(owner.project !== undefined ? { project: owner.project } : {}),
+      generation: (current?.generation ?? 0) + 1,
+      acquired_at: nowIso,
+      refreshed_at: nowIso,
+      expires_at: expiresIso,
+    };
+    writeLease(dir, lease);
+    return { ok: true, lease, fresh: true };
+  });
+}
+
+export interface DesktopLeaseDeps {
+  /** Async sleep used while waiting for another owner's lease. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/** Build a lease API; tests inject `sleep` (and `LeaseOptions.now`). */
+export function createDesktopLease(deps: DesktopLeaseDeps = {}): LeaseApi {
+  const sleep =
+    deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+  return {
+    async acquire(owner: LeaseOwner, opts: LeaseOptions): Promise<LeaseAcquireResult> {
+      const now = opts.now ?? Date.now;
+      const idleMs = opts.idleMs ?? DEFAULT_LEASE_IDLE_MS;
+      const waitMs = Math.max(0, opts.waitMs ?? 0);
+      const pollMs = Math.max(1, opts.pollMs ?? DEFAULT_POLL_MS);
+      mkdirSync(opts.dir, { recursive: true });
+      const started = now();
+      // Track slept time too, so a frozen injected clock cannot wait forever.
+      let slept = 0;
+      for (;;) {
+        const result = tryAcquire(owner, opts.dir, now(), idleMs);
+        const waited = Math.max(now() - started, slept);
+        if (result.ok) return result;
+        const remaining = waitMs - waited;
+        if (remaining <= 0) return { ok: false, holder: result.holder, waitedMs: waited };
+        const step = Math.min(pollMs, remaining);
+        await sleep(step);
+        slept += step;
+      }
+    },
+
+    release(owner: LeaseOwner, opts: LeaseOptions): boolean {
+      try {
+        if (!statSync(opts.dir).isDirectory()) return false;
+      } catch {
+        return false;
+      }
+      return withLock(opts.dir, () => {
+        const current = readRaw(opts.dir);
+        if (!current || current.owner_id !== owner.id) return false;
+        const nowMs = (opts.now ?? Date.now)();
+        if (isExpired(current, nowMs)) return false;
+        // Expire the record instead of deleting it, so the next owner's
+        // generation still counts up from this one.
+        const nowIso = new Date(nowMs).toISOString();
+        writeLease(opts.dir, { ...current, refreshed_at: nowIso, expires_at: nowIso });
+        return true;
+      });
+    },
+
+    read(opts: LeaseOptions): DesktopLease | null {
+      const now = opts.now ?? Date.now;
+      const lease = readRaw(opts.dir);
+      return lease && !isExpired(lease, now()) ? lease : null;
+    },
+  };
+}
+
+export const desktopLease: LeaseApi = createDesktopLease();

package/src/lib/computer/types.ts

@@ -0,0 +1,177 @@
+/**
+ * Shared contracts for `harn computer` (ADR 0228).
+ *
+ * The command layer and the desktop lease depend only on these types. Every
+ * driver-specific detail (release URLs, archive layout, CLI arguments, config
+ * files) lives behind `DesktopDriver` in a driver module such as `cua.ts`.
+ *
+ * Internal module: not exported from package.json.
+ */
+
+/** Where the desktop being driven lives, relative to the calling process. */
+export type HostKind =
+  /** A native Windows process driving its own desktop. */
+  | "windows"
+  /** A WSL2 process driving the Windows desktop through interop. */
+  | "wsl"
+  /** Any host without a supported driver build (macOS, Linux desktops). */
+  | "unsupported";
+
+export interface HostInfo {
+  kind: HostKind;
+  /** Human-readable reason when kind is "unsupported". */
+  reason?: string;
+  /**
+   * Directory (in the CALLER's path syntax) that is shared by every caller of
+   * this desktop: on Windows and WSL, `%LOCALAPPDATA%\harnery` expressed as a
+   * Windows path (windows) or its `/mnt/<drive>/...` form (wsl). The lease file
+   * and driver installs live under it.
+   */
+  desktopStateDir?: string;
+}
+
+/** A pinned, checksum-verified build of one driver for one platform. */
+export interface PinnedArtifact {
+  /** Driver version, e.g. "0.38.0". */
+  version: string;
+  /** Archive file name as published. */
+  fileName: string;
+  /** Download URL. */
+  url: string;
+  /** Lowercase hex SHA-256 of the archive. */
+  sha256: string;
+  /** Path of the driver executable inside the archive. */
+  executableEntry: string;
+}
+
+export interface InstallPlan {
+  driver: string;
+  version: string;
+  host: HostKind;
+  artifact: PinnedArtifact;
+  /** Install directory in the caller's path syntax (versioned). */
+  installDir: string;
+  /** Executable path in the caller's path syntax. */
+  executable: string;
+  /** Already installed and the executable's archive hash was verified at install time. */
+  alreadyInstalled: boolean;
+  /** Driver preference file written before first run, caller's path syntax. */
+  preferenceFile: string;
+  /** Preferences merged into that file (e.g. telemetry off). */
+  preferences: Record<string, unknown>;
+}
+
+export interface InstallResult extends InstallPlan {
+  installed: boolean;
+}
+
+export interface DaemonStatus {
+  running: boolean;
+  /** Raw first line(s) from the driver's status output, for display. */
+  detail: string;
+  pid?: number;
+}
+
+export interface DriverCallResult {
+  /** Process exit code of the driver invocation. */
+  exitCode: number;
+  /** Driver stdout with CRLF normalized to LF. */
+  stdout: string;
+  /** Driver stderr with CRLF normalized to LF. */
+  stderr: string;
+  /** Parsed stdout when it is a single JSON value, else undefined. */
+  json?: unknown;
+}
+
+/**
+ * The adapter boundary. One implementation today (`cua.ts`); a second driver
+ * would implement this interface rather than branch inside the command.
+ */
+export interface DesktopDriver {
+  /** Stable id, e.g. "cua". */
+  readonly id: string;
+  /** Pinned version this Harnery build installs. */
+  readonly version: string;
+  /** Resolve the install plan for this host without side effects. */
+  planInstall(host: HostInfo): InstallPlan;
+  /** Download, verify, extract and write preferences. Idempotent. */
+  install(plan: InstallPlan): Promise<InstallResult>;
+  /** Executable path if the pinned version is installed, else undefined. */
+  installedExecutable(host: HostInfo): string | undefined;
+  daemonStatus(host: HostInfo): DaemonStatus;
+  /** Start the daemon unelevated if it is not running. Returns the new status. */
+  startDaemon(host: HostInfo): Promise<DaemonStatus>;
+  stopDaemon(host: HostInfo): DaemonStatus;
+  /** One tool call. `args` is the JSON object passed to the tool. */
+  call(host: HostInfo, tool: string, args: Record<string, unknown>): DriverCallResult;
+  /** Tool catalog lines ("name: description"). */
+  listTools(host: HostInfo): DriverCallResult;
+  /** Full description + input schema of one tool. */
+  describe(host: HostInfo, tool: string): DriverCallResult;
+  /** End-to-end diagnostics (driver's own health report). */
+  health(host: HostInfo): DriverCallResult;
+  /**
+   * Rewrite caller-side paths inside tool args to the driver's path syntax
+   * (e.g. WSL `/home/...` -> `\\wsl.localhost\...`, `/mnt/c/...` -> `C:\...`),
+   * and the reverse for paths in results. Identity on native hosts.
+   */
+  translateArgsPaths(
+    host: HostInfo,
+    tool: string,
+    args: Record<string, unknown>,
+  ): Record<string, unknown>;
+  translateResultPaths(host: HostInfo, stdout: string): string;
+}
+
+/** Who is asking for the desktop. Resolved by the command layer. */
+export interface LeaseOwner {
+  /** Stable id: the agent instance id, or `pid:<pid>@<host>` without one. */
+  id: string;
+  /** Display label, e.g. "agent-Dexter". Also the default driver session. */
+  label: string;
+  /** Project root of the caller, informational. */
+  project?: string;
+}
+
+/** On-disk lease record (one per desktop). */
+export interface DesktopLease {
+  schema: 1;
+  owner_id: string;
+  owner_label: string;
+  project?: string;
+  /** Increments on every fresh acquisition (no lease, or the previous one expired or was released). */
+  generation: number;
+  acquired_at: string;
+  refreshed_at: string;
+  /** ISO time after which the lease is free for anyone. */
+  expires_at: string;
+}
+
+export interface LeaseOptions {
+  /** Directory holding the lease file (HostInfo.desktopStateDir/computer). */
+  dir: string;
+  /** Idle expiry, refreshed on every acquire by the same owner. Default 120s. */
+  idleMs?: number;
+  /** How long to wait for another owner's lease. Default 0 (fail at once). */
+  waitMs?: number;
+  /** Poll interval while waiting. Default 500ms. */
+  pollMs?: number;
+  /** Injectable clock for tests. */
+  now?: () => number;
+}
+
+export type LeaseAcquireResult =
+  | {
+      ok: true;
+      lease: DesktopLease /** true when this call took the lease from nobody/expired. */;
+      fresh: boolean;
+    }
+  | { ok: false; holder: DesktopLease; waitedMs: number };
+
+export interface LeaseApi {
+  acquire(owner: LeaseOwner, opts: LeaseOptions): Promise<LeaseAcquireResult>;
+  /** Release only if held by `owner`. Returns true when a lease was removed. */
+  release(owner: LeaseOwner, opts: LeaseOptions): boolean;
+  /** Current unexpired lease, or null. */
+  read(opts: LeaseOptions): DesktopLease | null;
+}

package/src/lib/docs-metadata-v2.ts

@@ -287,7 +287,13 @@ function validateRelations(
   const allowed = new Set(["depends_on", "supersedes", "superseded_by", "continues", "related"]);
   for (const [key, value] of Object.entries(data.relations)) {
     if (!allowed.has(key)) {
-      add(issues, "error", "unknown_relation", `relations.${key}`, `unknown relation '${key}'`);
+      add(
+        issues,
+        "error",
+        "unknown_relation",
+        `relations.${key}`,
+        `unknown relation '${key}'; use one of: ${[...allowed].join(", ")}`,
+      );
       continue;
     }
     validateStringList(value, `relations.${key}`, issues);
@@ -311,7 +317,7 @@ function validateAccess(
         "error",
         "unknown_access_field",
         `access.${key}`,
-        `unknown access field '${key}'`,
+        `unknown access field '${key}'; use ${[...allowed].join(" or ")}`,
       );
     }
   }
@@ -334,7 +340,13 @@ function validateLifecycle(
   const allowed =
     type === "plan" ? PLAN_STATUSES : type === "issue" ? ISSUE_STATUSES : HANDOFF_STATUSES;
   if (status && !allowed.has(status)) {
-    add(issues, "error", "invalid_status", "status", `status '${status}' is invalid for ${type}`);
+    add(
+      issues,
+      "error",
+      "invalid_status",
+      "status",
+      `status '${status}' is invalid for ${type}; use one of: ${[...allowed].join(", ")}`,
+    );
   }
 
   const changedAt = validateTimestamp(data, "status_changed_at", issues);
@@ -543,8 +555,15 @@ function validateInquiry(
 ): void {
   requireString(data, "title", issues);
   const status = requireString(data, "status", issues);
-  if (status && !new Set(["open", "resolved", "abandoned"]).has(status)) {
-    add(issues, "error", "invalid_status", "status", `inquiry status '${status}' is invalid`);
+  const inquiryStatuses = ["open", "resolved", "abandoned"];
+  if (status && !inquiryStatuses.includes(status)) {
+    add(
+      issues,
+      "error",
+      "invalid_status",
+      "status",
+      `inquiry status '${status}' is invalid; use one of: ${inquiryStatuses.join(", ")}`,
+    );
   }
   const changedAt = validateTimestamp(data, "status_changed_at", issues);
   if (createdAt !== null && changedAt !== null && changedAt < createdAt) {

package/src/lib/exec.ts

@@ -46,6 +46,7 @@ export function exec(cmd: string[], opts: ExecOpts = {}): Promise<ExecResult> {
   const [file, ...args] = cmd;
   return new Promise<ExecResult>((resolveResult) => {
     const proc = spawn(file, args, {
+      windowsHide: true,
       cwd: opts.cwd ?? process.cwd(),
       env: opts.env ?? { ...process.env },
       stdio: ["ignore", "pipe", "pipe"],

package/src/lib/guarded-remove.ts

@@ -92,7 +92,8 @@ export function guardedRemove(
     throw new Error("--root cannot be a filesystem root or home directory");
   assertEntryLimitAuthority();
   if (paths.length === 0 || paths.length > 100) throw new Error("Supply 1-100 explicit targets");
-  const targets = paths.map((path) => checkedPath(path, allowed));
+  // Relative targets name paths under --root, never under the process cwd.
+  const targets = paths.map((path) => checkedPath(path, allowed, false, root));
   const snapshots = new Map<string, string>();
   const removedProtected = new Set<string>();
   const links: RemovalLink[] = [];
@@ -349,7 +350,7 @@ function allowedProtected(
   for (const input of paths) {
     if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
       throw new Error("Use a nonempty explicit --allow-protected path without wildcards");
-    const path = resolve(input);
+    const path = resolve(root, input);
     let cursor = dirname(path);
     while (true) {
       if (lstatSync(cursor).isSymbolicLink())
@@ -435,10 +436,11 @@ function checkedPath(
   input: string,
   allowed: ReadonlySet<string> = new Set(),
   isRoot = false,
+  base?: string,
 ): string {
   if (!input?.trim() || /[\0\r\n*?[\]$]/.test(input))
     throw new Error("Use a nonempty explicit path without wildcards or unresolved variables");
-  const path = resolve(input);
+  const path = base === undefined ? resolve(input) : resolve(base, input);
   let cursor = path;
   while (true) {
     if (