@saadnvd1/agent-os 0.3.467 → 0.3.470

package/lib/orchestrator/write-guard.ts

@@ -0,0 +1,295 @@
+/**
+ * Where an orchestrator may write. Anywhere on the machine except the
+ * workspace's project repositories and their task worktrees (code changes go
+ * through tasks, so the merge gates keep meaning something), AgentOS's own
+ * install and state (all of ~/.agent-os but its own folder), secret files,
+ * and files that make something run: the dotfiles and dot-folders in its
+ * home (shell, git, Claude and tool config), ~/Library, the folders on PATH,
+ * and any .git, .claude, .mcp.json, CLAUDE.md or the like. A write to one of
+ * those would hand it a shell, or run code in AgentOS's own git, without
+ * touching a protected path itself. Its chat worker checks every Write, Edit and NotebookEdit here
+ * before it runs (a PreToolUse hook), on the path with every symlink and
+ * `..` resolved the way the system will resolve it.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { db, type Session } from "../db";
+import { git, GitError } from "../git-exec";
+import { isSecretPath } from "../secret-paths";
+import { WORKTREES_DIR } from "../worktrees";
+import { orchestratorDir } from "./home";
+import { LIMITS_FILE } from "./usage";
+
+// The tools that write a file, and the argument naming it.
+export const WRITE_TOOLS: Record<string, string> = {
+  Write: "file_path",
+  Edit: "file_path",
+  MultiEdit: "file_path",
+  NotebookEdit: "notebook_path",
+};
+
+export interface WriteBounds {
+  // Relative paths are taken from here.
+  cwd: string;
+  // Its own folder, the one part of `state` it may write.
+  ownDir: string;
+  // AgentOS's state (~/.agent-os).
+  state: string;
+  // Project repositories, task worktrees and AgentOS's install.
+  repos: string[];
+  // Its home: no dotfile or dot-folder in it may be written.
+  home: string;
+  // Folders whose files run (~/Library, PATH, the usage brake's input...).
+  runs: string[];
+}
+
+// Wherever they are, files that configure what an agent, git or a
+// language runtime runs.
+const RUNS_CODE =
+  /(^|\/)(\.git|\.claude|\.codex|\.cursor|\.vscode|\.husky|\.githooks)(\/|$)|(^|\/)(\.mcp\.json|\.claude\.json|CLAUDE(\.local)?\.md|AGENTS\.md|\.envrc|\.gitconfig|\.gitattributes|\.gitmodules|sitecustomize\.py|usercustomize\.py)$|\.pth$/i;
+
+// The temporary checkouts AgentOS reviews, rebases and writes PR bodies in
+// (repo.ts, rebase.ts): an edit while a review runs would change what it
+// judges.
+const AGENTOS_TEMP = /(^|\/)aos-(review|rebase|body)-[^/]+(\/|$)/;
+
+const MAX_LINKS = 40;
+
+// The path as the system resolves it: component by component from the root,
+// each symlink followed where it sits (a dangling one too, since a write
+// creates its target), and `..` taken from the real folder it's in. Parts
+// that don't exist yet are kept as named, under the real folder they'd be
+// made in.
+export async function physicalPath(p: string): Promise<string> {
+  const parts = p.split("/").filter(Boolean);
+  let at = "/";
+  let links = 0;
+  while (parts.length) {
+    const part = parts.shift()!;
+    if (part === ".") continue;
+    if (part === "..") {
+      at = path.dirname(at);
+      continue;
+    }
+    const next = path.join(at, part);
+    const link = await fs.promises.readlink(next).catch(() => null);
+    if (link === null) {
+      at = next;
+      continue;
+    }
+    if (++links > MAX_LINKS) throw new Error("Too many symlinks");
+    parts.unshift(...link.split("/").filter(Boolean));
+    if (link.startsWith("/")) at = "/";
+  }
+  return canonical(at);
+}
+
+// Its deepest existing folder as the file system spells it, so a path in
+// another case or Unicode form (one folder on macOS) compares equal.
+async function canonical(p: string): Promise<string> {
+  const rest: string[] = [];
+  let at = p;
+  for (;;) {
+    try {
+      return path.join(await fs.promises.realpath(at), ...rest.reverse());
+    } catch {
+      const up = path.dirname(at);
+      if (up === at) return p;
+      rest.push(path.basename(at));
+      at = up;
+    }
+  }
+}
+
+const FOLDS_CASE =
+  process.platform === "darwin" || process.platform === "win32";
+const key = (p: string) =>
+  FOLDS_CASE ? p.normalize("NFC").toLowerCase() : p.normalize("NFC");
+
+const within = (p: string, root: string) => {
+  const [a, b] = [key(p), key(root)];
+  return a === b || a.startsWith(b === "/" ? b : b + "/");
+};
+
+const expandHome = (p: string) => p.replace(/^~(?=$|\/)/, os.homedir());
+
+// Why a write to this path is refused, or null when it may go ahead.
+export async function writeRefusal(
+  filePath: string,
+  bounds: WriteBounds
+): Promise<string | null> {
+  if (!filePath) return "No file path to check.";
+  const given = expandHome(filePath);
+  const abs = given.startsWith("/") ? given : `${bounds.cwd}/${given}`;
+  let targets: string[];
+  let repos: string[];
+  let state: string[];
+  let ownDir: string[];
+  let home: string[];
+  let runs: string[];
+  try {
+    // Where it lands as written, and with `..` taken by name first, as a
+    // tool that normalises the path before opening it would; and where it
+    // was asked for, before any link: all must be allowed. A link sitting in
+    // a protected place (a dotfile kept in a dotfiles repo, Homebrew's
+    // bin/git) is refused there, wherever it points.
+    targets = [
+      ...new Set([
+        ...(await Promise.all([
+          physicalPath(abs),
+          physicalPath(path.resolve(abs)),
+        ])),
+        path.resolve(abs),
+      ]),
+    ];
+    // Each folder by its own name too, for a path that reaches it by name.
+    const both = async (p: string) => [path.resolve(p), await physicalPath(p)];
+    repos = (await Promise.all(bounds.repos.map(both))).flat();
+    runs = (await Promise.all(bounds.runs.map(both))).flat();
+    state = await both(bounds.state);
+    ownDir = await both(bounds.ownDir);
+    home = await both(bounds.home);
+  } catch (e) {
+    return `Couldn't resolve ${filePath}: ${(e as Error).message}.`;
+  }
+  for (const target of targets) {
+    const repo = repos.find((r) => within(target, r));
+    if (repo)
+      return `${filePath} is inside ${repo}, a project repository, task worktree or AgentOS itself. Change code there through a task (start_task), so its PR goes through the merge gates.`;
+    if (AGENTOS_TEMP.test(target))
+      return `${filePath} is in a checkout AgentOS is reviewing or rebasing; orchestrators never write there.`;
+    const own = ownDir.some((d) => within(target, d));
+    if (state.some((d) => within(target, d)) && !own)
+      return `${filePath} is in AgentOS's own state (${bounds.state}); you may write only in your folder, ${bounds.ownDir}.`;
+    if (isSecretPath(target) || isSecretPath(filePath))
+      return `${filePath} holds or guards secrets; orchestrators never write those.`;
+    const runsIn = runs.find((r) => within(target, r));
+    if (
+      RUNS_CODE.test(target) ||
+      RUNS_CODE.test(filePath) ||
+      runsIn ||
+      (!own &&
+        home.some(
+          (h) =>
+            within(target, h) &&
+            key(target)
+              .slice(key(h).length + 1)
+              .startsWith(".")
+        ))
+    )
+      return `${filePath} configures what runs (shell, git, agent or tool config${runsIn ? `, in ${runsIn}` : ""}); orchestrators never write those.`;
+  }
+  return null;
+}
+
+// What an orchestrator's writes are held to, read fresh for each one so a
+// project added since counts: every local project's repositories (not just
+// its workspace's, since a write to another workspace's repo skips its gates
+// as much), every session's worktree, and AgentOS's install and database.
+export async function orchestratorWriteBounds(
+  session: Session
+): Promise<WriteBounds> {
+  const projects = db
+    .prepare(
+      `SELECT working_directory AS dir FROM projects
+        WHERE is_uncategorized = 0 AND host_id = 'local'
+       UNION SELECT r.path FROM project_repositories r
+         JOIN projects p ON p.id = r.project_id
+        WHERE p.host_id = 'local'
+       UNION SELECT worktree_path FROM sessions
+        WHERE worktree_path IS NOT NULL AND worktree_path != ''`
+    )
+    .all() as { dir: string }[];
+  const dbPath = path.resolve(
+    process.env.DB_PATH || path.join(process.cwd(), "agent-os.db")
+  );
+  const repos = projects.map((p) => expandHome(p.dir)).filter((d) => d !== "");
+  return {
+    cwd: expandHome(session.working_directory),
+    home: os.homedir(),
+    runs: [
+      path.join(os.homedir(), "Library"),
+      "/Library/LaunchAgents",
+      "/Library/LaunchDaemons",
+      path.dirname(LIMITS_FILE),
+      ...(await hooksPaths(repos)),
+      ...(process.env.XDG_CONFIG_HOME ? [process.env.XDG_CONFIG_HOME] : []),
+      ...(process.env.PATH ?? "").split(":").filter((d) => d.startsWith("/")),
+    ],
+    ownDir: orchestratorDir(session.workspace_id ?? ""),
+    state: path.join(os.homedir(), ".agent-os"),
+    repos: [...repos, WORKTREES_DIR, process.cwd(), path.dirname(dbPath)],
+  };
+}
+
+// Where git looks for hooks instead of .git/hooks (core.hooksPath), in the
+// user's config and each project's: a script there runs on the next commit.
+// Read at most once a minute, not on every write.
+const HOOKS_TTL_MS = 60_000;
+let hooksCache: { key: string; at: number; dirs: string[] } | null = null;
+
+export async function hooksPaths(repos: string[]): Promise<string[]> {
+  const key = repos.join("\0");
+  if (hooksCache?.key === key && Date.now() - hooksCache.at < HOOKS_TTL_MS)
+    return hooksCache.dirs;
+  // Only "not set" and "not a repository" mean there's nothing to protect;
+  // any other failure (a timeout under load) throws, so the write is
+  // refused and nothing is cached.
+  const run = (cwd: string, args: string[]) =>
+    git(cwd, args, { timeout: 5000 })
+      .then((out) => out.trim())
+      .catch((e: unknown) => {
+        if (
+          e instanceof GitError &&
+          !e.timedOut &&
+          (e.exitCode === 1 || /not a git repository/i.test(e.stderr))
+        )
+          return "";
+        throw new Error(`couldn't read git's hooks folder in ${cwd}`);
+      });
+  // The user's, expanded by git (~ and ~user). A relative one is taken from
+  // each repo's top, so it names no one folder: each project's answer
+  // below covers it there. Each project's comes as git itself resolves it.
+  const global = await run(os.homedir(), [
+    "config",
+    "--global",
+    "--type=path",
+    "--get",
+    "core.hooksPath",
+  ]);
+  const found = await Promise.all(
+    repos.map(async (r) => {
+      // A project whose folder is gone has no hooks to run.
+      if (!fs.existsSync(r)) return "";
+      const dir = await run(r, [
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-path",
+        "hooks",
+      ]);
+      if (dir !== "" && !dir.startsWith("/"))
+        throw new Error(`git named no folder for ${r}'s hooks`);
+      return dir;
+    })
+  );
+  const dirs = [
+    ...new Set([global, ...found].filter((d) => d.startsWith("/"))),
+  ];
+  hooksCache = { key, at: Date.now(), dirs };
+  return dirs;
+}
+
+// The check a PreToolUse hook makes: why this tool call is refused, or null.
+export async function orchestratorToolRefusal(
+  session: Session,
+  tool: string,
+  input: Record<string, unknown>
+): Promise<string | null> {
+  const arg = WRITE_TOOLS[tool];
+  if (!arg) return null;
+  const filePath = input[arg];
+  if (typeof filePath !== "string") return "No file path to check.";
+  return writeRefusal(filePath, await orchestratorWriteBounds(session));
+}

package/lib/project-add/index.ts

@@ -3,15 +3,25 @@
  * into it, or start a new one from a name (folder, git init, first commit).
  */
 
+import os from "os";
 import path from "path";
 import { randomUUID } from "crypto";
-import { createProject, type ProjectWithRepositories } from "../projects";
+import {
+  createProject,
+  getProject,
+  getProjectWithDevServers,
+  type ProjectWithRepositories,
+} from "../projects";
+import { db, queries, type Project } from "../db";
 import { getHost } from "../hosts";
+import { getWorkspace, setProjectWorkspace } from "../workspaces";
 import { shellQuote } from "../hosts/ssh";
 import { run, shellPath, spawnOn } from "./shell";
 import { onWindowsDrive, WINDOWS_DRIVE_WARNING } from "../wsl";
 
-export const PROJECT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+import { PROJECT_NAME } from "./name";
+
+export { PROJECT_NAME };
 // https://host/owner/repo(.git), ssh://…, or git@host:owner/repo(.git).
 const REPO_URL =
   /^(?:https:\/\/[\w.-]+(?::\d+)?\/|ssh:\/\/[\w.@-]+(?::\d+)?\/|[\w.-]+@[\w.-]+:)[\w./~-]+$/;
@@ -25,6 +35,8 @@ export interface FolderListing {
   parent: string | null;
   folders: string[];
   isGitRepo: boolean;
+  // The folder with every symlink resolved, for the secrets check.
+  realPath: string;
   // Set when the folder is somewhere a project shouldn't live (a Windows
   // drive under WSL).
   warning: string | null;
@@ -38,28 +50,129 @@ export async function listFolders(
   checkHost(hostId);
   const out = await run(
     hostId,
-    `cd ${shellPath(dir || "~")} && pwd && { test -e .git && echo GIT || echo NOGIT; } && find . -mindepth 1 -maxdepth 1 -type d ! -name '.*' 2>/dev/null | sort | head -500`
+    `cd ${shellPath(dir || "~")} && pwd && pwd -P && { test -e .git && echo GIT || echo NOGIT; } && find . -mindepth 1 -maxdepth 1 -type d ! -name '.*' 2>/dev/null | sort | head -500`
   );
-  const [abs, git, ...rest] = out.split("\n");
+  const [abs, real, git, ...rest] = out.split("\n");
   return {
     path: abs,
     parent: abs === "/" ? null : path.posix.dirname(abs),
     folders: rest.filter(Boolean).map((f) => f.replace(/^\.\//, "")),
     isGitRepo: git === "GIT",
+    realPath: real,
     warning: onWindowsDrive(abs) ? WINDOWS_DRIVE_WARNING : null,
   };
 }
 
+function checkWorkspace(workspaceId: string | null | undefined) {
+  if (workspaceId && !getWorkspace(workspaceId))
+    throw new Error("Unknown workspace");
+}
+
+// Folders that hold keys and credentials are never a project's home.
+const SECRET_DIR =
+  /(^|\/)(\.ssh|\.gnupg|\.aws|\.azure|\.kube|\.docker|\.password-store|\.agent-os|Keychains|tokenvault)(\/|$)/i;
+
+export function isSecretPath(dir: string): boolean {
+  const p = dir.replace(os.homedir(), "~");
+  return SECRET_DIR.test(p) || /^~\/\.config(\/|$)/i.test(p);
+}
+
+const folderKey = (hostId: string, dir: string) => {
+  const abs =
+    hostId === "local" ? dir.replace(/^~(?=$|\/)/, os.homedir()) : dir;
+  return `${hostId}\0${abs.replace(/\/+$/, "") || "/"}`;
+};
+
+// The project that already lives in this folder on this machine, if any.
+export function projectAt(hostId: string, dir: string): Project | null {
+  const key = folderKey(hostId, dir);
+  const row = (
+    queries.getProjectFolders(db).all() as {
+      id: string;
+      host_id: string;
+      working_directory: string;
+      is_uncategorized: number;
+    }[]
+  ).find(
+    (p) =>
+      !p.is_uncategorized &&
+      folderKey(p.host_id || "local", p.working_directory) === key
+  );
+  return (row && getProject(row.id)) || null;
+}
+
+// Adding a folder that's already a project: the caller is told which, and
+// can ask again with moveExisting to bring it into the workspace instead.
+export class ProjectExistsError extends Error {
+  constructor(readonly project: Project) {
+    super(`${project.name} is already a project`);
+  }
+}
+
+export interface AddFolderOptions {
+  workspaceId?: string | null;
+  name?: string;
+  // An existing project at the folder moves into workspaceId rather than
+  // failing.
+  moveExisting?: boolean;
+  // ...but only one in no workspace: taking a project from another
+  // workspace is refused (the orchestrator's limit).
+  moveOnlyUnassigned?: boolean;
+  requireGit?: boolean;
+}
+
+export interface AddedFolder {
+  project: ProjectWithRepositories;
+  // What happened: made, or an existing one moved (from its old
+  // workspace) or already there.
+  outcome: "created" | "moved" | "unchanged";
+  from: string | null;
+}
+
+// The one way a folder becomes a project in a workspace, for the add
+// dialog and the orchestrator's add_project alike.
 export async function addFolder(
   hostId: string,
-  dir: string
-): Promise<ProjectWithRepositories> {
-  const { path: abs } = await listFolders(hostId, dir);
-  return createProject({
-    name: path.posix.basename(abs) || "project",
-    workingDirectory: abs,
-    hostId,
-  });
+  dir: string,
+  opts: AddFolderOptions = {}
+): Promise<AddedFolder> {
+  checkHost(hostId);
+  checkWorkspace(opts.workspaceId);
+  if (isSecretPath(dir)) throw new Error("That folder holds secrets");
+  const { path: abs, realPath, isGitRepo } = await listFolders(hostId, dir);
+  if (isSecretPath(abs) || isSecretPath(realPath))
+    throw new Error("That folder holds secrets");
+  if (opts.requireGit && !isGitRepo)
+    throw new Error(`${abs} isn't a git repository`);
+  const workspaceId = opts.workspaceId ?? null;
+  const existing = projectAt(hostId, abs) ?? projectAt(hostId, realPath);
+  if (existing) {
+    if (!opts.moveExisting) throw new ProjectExistsError(existing);
+    const from = existing.workspace_id;
+    if (opts.moveOnlyUnassigned && from && from !== workspaceId)
+      throw new Error(
+        `${existing.name} belongs to the ${getWorkspace(from)?.name ?? "another"} workspace; only Saad moves a project between workspaces`
+      );
+    const outcome =
+      !workspaceId || from === workspaceId ? "unchanged" : "moved";
+    if (outcome === "moved") setProjectWorkspace(existing.id, workspaceId);
+    return {
+      project: getProjectWithDevServers(existing.id) as ProjectWithRepositories,
+      outcome,
+      from,
+    };
+  }
+  const name = opts.name?.trim() || path.posix.basename(abs) || "project";
+  return {
+    project: createProject({
+      name,
+      workingDirectory: abs,
+      hostId,
+      workspaceId,
+    }),
+    outcome: "created",
+    from: null,
+  };
 }
 
 // A machine with no git identity still gets its first commit, under a
@@ -71,9 +184,11 @@ const IDENTITY =
 export async function initProject(
   hostId: string,
   parent: string,
-  name: string
+  name: string,
+  workspaceId: string | null = null
 ): Promise<ProjectWithRepositories> {
   checkHost(hostId);
+  checkWorkspace(workspaceId);
   if (!PROJECT_NAME.test(name))
     throw new Error("Use letters, numbers, dots, dashes or underscores");
   const out = await run(
@@ -84,6 +199,7 @@ export async function initProject(
     name,
     workingDirectory: out.trim().split("\n").pop() || name,
     hostId,
+    workspaceId,
   });
 }
 
@@ -119,9 +235,11 @@ export const getCloneJob = (id: string) => jobs.get(id) ?? null;
 export function startClone(
   hostId: string,
   parent: string,
-  url: string
+  url: string,
+  workspaceId: string | null = null
 ): CloneJob {
   checkHost(hostId);
+  checkWorkspace(workspaceId);
   if (!REPO_URL.test(url)) throw new Error("That isn't a repository URL");
   const name = repoNameOf(url);
   if (!name) throw new Error("Couldn't tell the repository's name");
@@ -182,6 +300,7 @@ export function startClone(
         name,
         workingDirectory: stdout.trim().split("\n").pop() || name,
         hostId,
+        workspaceId,
       });
       job.projectId = project.id;
       job.status = "done";

package/lib/project-add/name.ts

@@ -0,0 +1 @@
+export const PROJECT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;

package/lib/secret-paths.ts

@@ -0,0 +1,9 @@
+// Files that hold or guard secrets: env files, keys, credential stores and
+// the folders keys live in (.ssh, .aws, .gnupg, .kube, .docker, gh, gcloud,
+// tokenvault). Tested against a repo-relative or absolute path. A merge that
+// touches one goes to Saad (lib/orchestrator/diff), and an orchestrator may
+// never write one (lib/orchestrator/write-guard).
+export const SECRET_PATH =
+  /(^|\/)\.env(\.[^/]*)?$|(^|\/)[^/]*(secret|credential|tokenvault|keychain)[^/]*(\/|$)|\.(pem|key|p12|pfx)$|(^|\/)(id_(rsa|dsa|ecdsa|ed25519)|\.npmrc|\.netrc|\.pgpass)$|(^|\/)\.(ssh|aws|azure|gnupg|kube|docker)(\/|$)|(^|\/)\.config\/(gh|gcloud|op)(\/|$)/i;
+
+export const isSecretPath = (p: string): boolean => SECRET_PATH.test(p);

package/lib/tasks/finish.ts

@@ -75,8 +75,14 @@ async function cleanup(
 export const signingOff = new Set<string>();
 
 // What happens after a merge: restack anything stacked on it, then remove the
-// session, worktree and branch. Kept per task so Land can wait for it.
-const afterMerge = new Map<string, Promise<void>>();
+// session, worktree and branch. Kept per task so Land and done can wait for
+// it; on globalThis because the watcher's merges run in server.ts and done in
+// a route bundle, which load this module separately.
+const g = globalThis as unknown as {
+  __agentosAfterMerge?: Map<string, Promise<void>>;
+};
+const afterMerge: Map<string, Promise<void>> = (g.__agentosAfterMerge ??=
+  new Map());
 
 async function finishMerge(
   session: Session,

package/lib/worktree-removal.ts

@@ -0,0 +1,115 @@
+/**
+ * Removals of a worktree in progress, visible to every reader. `git
+ * worktree remove` takes seconds on a tree with cloned dependencies, and a
+ * tree read halfway through lists every file it already deleted as an
+ * uncommitted change. The removal that a merge's cleanup starts runs in
+ * server.ts while done runs in a route bundle (each loads its own copy of
+ * a module) or another process, so besides the in-memory record a marker
+ * file beside the worktree says a removal is running.
+ */
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+export interface Removal {
+  done: Promise<void>;
+  // The branch the worktree was on, read before anything was removed.
+  branch: Promise<string | null>;
+}
+
+const g = globalThis as unknown as { __agentosRemovals?: Map<string, Removal> };
+export const removals: Map<string, Removal> = (g.__agentosRemovals ??=
+  new Map());
+
+export const removalKey = (p: string) =>
+  path.resolve(p.replace(/^~/, os.homedir()));
+
+// Beside the worktree, not in it: git never lists it and the removal
+// doesn't delete it.
+export const removalMarker = (key: string) =>
+  path.join(path.dirname(key), `.${path.basename(key)}.removing`);
+
+// A marker older than this, or whose process is gone, is from a removal
+// cut short (a restart) and no longer means anything.
+const STALE_MS = 10 * 60_000;
+
+// Returns what it wrote, so only the removal that wrote it clears it.
+export function markRemoving(key: string): string | null {
+  const marker = removalMarker(key);
+  const tmp = `${marker}.${process.pid}`;
+  const body = JSON.stringify({ pid: process.pid, at: Date.now() });
+  try {
+    fs.writeFileSync(tmp, body);
+    fs.renameSync(tmp, marker);
+    return body;
+  } catch {
+    // No marker only means other processes can't see this removal.
+    return null;
+  }
+}
+
+export function unmarkRemoving(key: string, body: string): void {
+  const marker = removalMarker(key);
+  try {
+    if (fs.readFileSync(marker, "utf8") === body) fs.rmSync(marker);
+  } catch {
+    // Already gone.
+  }
+}
+
+const alive = (pid: number) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+};
+
+function markerLive(key: string): boolean {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(removalMarker(key), "utf8");
+  } catch {
+    return false;
+  }
+  try {
+    const { pid, at } = JSON.parse(raw) as { pid: number; at: number };
+    return Date.now() - at < STALE_MS && alive(pid);
+  } catch {
+    return false;
+  }
+}
+
+// Whether any code path or process is removing this worktree now.
+export const removalRunning = (worktreePath: string) => {
+  const key = removalKey(worktreePath);
+  return removals.has(key) || markerLive(key);
+};
+
+const sleep = (ms: number) =>
+  new Promise<void>((r) => setTimeout(r, Math.max(0, ms)));
+
+/**
+ * Resolves once no removal of this worktree is running: true, or false
+ * when one still is after `timeoutMs`. `foreignOnly` waits only for one
+ * another process (or a copy of this module) marked.
+ */
+export async function removalSettled(
+  worktreePath: string,
+  timeoutMs = 60_000,
+  { foreignOnly = false } = {}
+): Promise<boolean> {
+  const key = removalKey(worktreePath);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const own = foreignOnly ? undefined : removals.get(key);
+    if (!own && !markerLive(key)) return true;
+    const left = deadline - Date.now();
+    if (left <= 0) return false;
+    await (own
+      ? Promise.race([own.done.catch(() => {}), sleep(left)])
+      : sleep(Math.min(250, left)));
+  }
+}