@app-vitals/agent-runtime 0.0.1 → 0.1.1

package/worktree-reaper.ts

@@ -0,0 +1,244 @@
+/**
+ * agent/src/runtime/worktree-reaper.ts
+ *
+ * Stale-worktree age sweep (WTR-1.2) — a pure-filesystem background pass
+ * that force-removes `worktrees/<repo>-<branch>` directories that have gone
+ * stale (older than the configured cleanup_after_days),
+ * mirroring the workspace CLAUDE.md instruction that worktrees older than 14
+ * days are removed automatically.
+ *
+ * Unlike pr-state-reconciler.ts, this module makes NO GitHub or task-store
+ * calls — it only reads the synced policy refs, lists the worktrees/ directory,
+ * checks mtimes against an injected clock, and runs `git worktree remove
+ * --force` for stale matches. It reuses WTR-1.1's readCleanupMergedWorktrees
+ * / readCleanupAfterDays (check-helpers.ts) rather than reimplementing
+ * policy reads.
+ *
+ * Shape mirrors pr-state-reconciler.ts: an injected-deps interface, a pure
+ * `reconcileStaleWorktrees(deps)` core function, per-directory try/catch
+ * error isolation (console.error, not console.warn — matches
+ * reconcilePrState's per-record loop) so one bad directory can't abort the
+ * rest of the batch, and a `buildProductionDeps()` factory wiring real
+ * fs/git calls at the bottom.
+ *
+ * Wired into agent/src/index.ts's PR-state-reconciler setInterval (WTR-1.4)
+ * as a third, independent try/catch pass on the same tick — see the Step 5b
+ * doc comment in index.ts for the full rationale.
+ */
+
+import { execFile } from "node:child_process";
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { readCleanupAfterDays } from "./cleanup-after-days-ref.ts";
+import { readCleanupMergedWorktrees } from "./cleanup-merged-worktrees-ref.ts";
+import type { Clock } from "./clock.ts";
+import { SystemClock } from "./clock.ts";
+import { resolveWorkspacePath, splitOrgRepo } from "./workspace-paths.ts";
+
+const execFileAsync = promisify(execFile);
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** A single `removeWorktree(repo, dirname)` invocation — exported for test-fixture typing. */
+export interface RemoveWorktreeCall {
+  repo: string;
+  dirname: string;
+}
+
+export interface WorktreeReaperDeps {
+  /** Reads the `cleanup_merged_worktrees` policy field. */
+  readCleanupMergedWorktrees: () => Promise<boolean>;
+  /** Reads the `cleanup_after_days` policy field. */
+  readCleanupAfterDays: () => Promise<number>;
+  /** Lists dirnames directly under worktrees/ (not full paths). */
+  listWorktreeDirs: () => string[];
+  /**
+   * Returns the agent's currently-configured repo scope, read fresh on
+   * every reconcileStaleWorktrees() call — mirrors PrStateReconcilerDeps's
+   * own getScopedRepos field, so a scope change (a repo added/removed via
+   * syncConfig()) is picked up on the very next reconcile pass instead of
+   * being frozen at first-tick memoization time.
+   */
+  getScopedRepos: () => string[];
+  /** mtime lookup for a given worktree dirname. */
+  statMtime: (dirname: string) => Date;
+  /** Force-removes a worktree: `git -C repos/{repo} worktree remove worktrees/{dirname} --force`. */
+  removeWorktree: (repo: string, dirname: string) => Promise<void>;
+  /** Injected time source — never call Date.now()/new Date() directly. */
+  clock: Clock;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * Resolve the scoped repo that owns a worktree dirname via longest-prefix
+ * match.
+ *
+ * `worktrees/<dirname>` uses the BARE repo name convention (e.g.
+ * "ok-wow-agency-feat-foo"), but agentReposRef.get() (and therefore
+ * deps.getScopedRepos()) returns "org/repo"-formatted strings in production
+ * (see agent-repos-ref.ts's doc comment) — so every scoped entry is first
+ * normalized to its bare repo name via splitOrgRepo() (the same helper
+ * pr-state-reconciler.ts uses to derive its own worktree dirname prefix from
+ * `record.repo`) before comparing against dirname. An entry with no "/" is
+ * already bare and normalizes to itself, which keeps the pre-RCO-1.1 bare-
+ * name-only scope format meaningful and matching unchanged.
+ *
+ * Repo names can themselves contain dashes (e.g. "example-repo"), so a naive
+ * first-dash split of dirname is unsafe — instead every normalized bare name
+ * is checked as a candidate prefix (`dirname === bareName` or
+ * `dirname.startsWith(bareName + "-")`, so a match only counts at a "-"
+ * boundary, never mid-word) and the LONGEST matching bare name wins (so
+ * "example-repo" wins over a hypothetical shorter false-positive prefix like
+ * "example").
+ *
+ * Ambiguity guard: two DISTINCT scoped "org/repo" entries can normalize to
+ * the SAME bare name (e.g. "org-a/widget" and "org-b/widget" both ->
+ * "widget") — the bare-dirname worktree convention has no way to tell them
+ * apart. Rather than arbitrarily picking one org's repo and silently
+ * mismatching the worktree (which could point `git worktree remove` at the
+ * wrong repo's local clone), a same-bare-name collision among the
+ * longest-matching entries is treated as unmatched (null), same as "no
+ * match" from the caller's point of view, but logged distinctly by the
+ * caller-visible sentinel below so it doesn't read as an ordinary
+ * "no scoped repo matches" case in Sentry.
+ */
+const AMBIGUOUS_MATCH = Symbol("ambiguous-match");
+
+function resolveOwningRepo(
+  dirname: string,
+  scopedRepos: string[],
+): string | null | typeof AMBIGUOUS_MATCH {
+  let bestBareName: string | null = null;
+  let bestOriginals: Set<string> = new Set();
+
+  for (const repo of scopedRepos) {
+    const [, bareName] = splitOrgRepo(repo);
+    if (!bareName) continue; // defensive — e.g. a malformed "org/" entry
+    const isMatch = dirname === bareName || dirname.startsWith(`${bareName}-`);
+    if (!isMatch) continue;
+
+    if (bestBareName === null || bareName.length > bestBareName.length) {
+      bestBareName = bareName;
+      bestOriginals = new Set([repo]);
+    } else if (bareName.length === bestBareName.length) {
+      bestOriginals.add(repo);
+    }
+  }
+
+  if (bestBareName === null) return null;
+  // Multiple distinct scoped entries tied for the longest match and share
+  // the same normalized bare name — e.g. "org-a/widget" + "org-b/widget".
+  // Note a single scoped entry appearing twice (or one repo matching under
+  // two different-length prefixes) never reaches here since bestOriginals
+  // is reset whenever a strictly longer bareName is found.
+  if (bestOriginals.size > 1) return AMBIGUOUS_MATCH;
+  return bestBareName;
+}
+
+/** True when `mtime` is older than `cleanupAfterDays` days before `now`. */
+function isStale(mtime: Date, now: Date, cleanupAfterDays: number): boolean {
+  const cutoff = now.getTime() - cleanupAfterDays * MS_PER_DAY;
+  return mtime.getTime() < cutoff;
+}
+
+// ─── Core logic ───────────────────────────────────────────────────────────────
+
+/**
+ * Scan worktrees/ for directories that have gone stale (older than the
+ * policy's cleanup_after_days) and force-remove each one via the injected
+ * removeWorktree dep. No-ops entirely (zero fs/git calls beyond reading the
+ * policy) when cleanup_merged_worktrees is false.
+ *
+ * A dirname whose prefix matches no scoped repo is skipped defensively
+ * (logged, not fatal). A single directory's removeWorktree failure is
+ * caught and logged; it does not abort processing of the remaining
+ * directories — mirrors pr-state-reconciler.ts's reconcilePrState per-record
+ * continue-on-error isolation.
+ */
+export async function reconcileStaleWorktrees(
+  deps: WorktreeReaperDeps,
+): Promise<void> {
+  if (!(await deps.readCleanupMergedWorktrees())) return; // disabled — no fs/git calls at all
+
+  const cleanupAfterDays = await deps.readCleanupAfterDays();
+  const now = deps.clock.now();
+
+  const dirs = deps.listWorktreeDirs();
+  const scopedRepos = deps.getScopedRepos();
+
+  for (const dirname of dirs) {
+    const repo = resolveOwningRepo(dirname, scopedRepos);
+    if (repo === AMBIGUOUS_MATCH) {
+      console.error(
+        `[worktree-reaper] skipping ${dirname} — AMBIGUOUS: multiple distinct scoped org/repo entries normalize to the same bare repo name for this worktree dirname's prefix`,
+      );
+      continue;
+    }
+    if (repo === null) {
+      console.error(
+        `[worktree-reaper] skipping ${dirname} — no scoped repo matches this worktree dirname's prefix`,
+      );
+      continue;
+    }
+
+    try {
+      const mtime = deps.statMtime(dirname);
+      if (!isStale(mtime, now, cleanupAfterDays)) continue; // still fresh — leave untouched
+
+      await deps.removeWorktree(repo, dirname);
+    } catch (err) {
+      console.error(
+        `[worktree-reaper] failed to reconcile worktree ${dirname}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+}
+
+// ─── Production deps ──────────────────────────────────────────────────────────
+
+/**
+ * Production deps for `reconcileStaleWorktrees()`. Reads the policy refs and
+ * worktrees/ from the resolved workspace path, and shells out to `git
+ * worktree remove --force` for the actual removal.
+ */
+export function buildProductionDeps(opts?: {
+  clock?: Clock;
+  getScopedRepos?: () => string[];
+}): WorktreeReaperDeps {
+  const workspacePath = resolveWorkspacePath();
+
+  return {
+    readCleanupMergedWorktrees: () => readCleanupMergedWorktrees(workspacePath),
+    readCleanupAfterDays: () => readCleanupAfterDays(workspacePath),
+    listWorktreeDirs: () => {
+      try {
+        return readdirSync(join(workspacePath, "worktrees"), {
+          withFileTypes: true,
+        })
+          .filter((entry) => entry.isDirectory())
+          .map((entry) => entry.name);
+      } catch {
+        return [];
+      }
+    },
+    getScopedRepos: opts?.getScopedRepos ?? (() => []),
+    statMtime: (dirname: string) =>
+      statSync(join(workspacePath, "worktrees", dirname)).mtime,
+    removeWorktree: async (repo: string, dirname: string) => {
+      await execFileAsync("git", [
+        "-C",
+        join(workspacePath, "repos", repo),
+        "worktree",
+        "remove",
+        join(workspacePath, "worktrees", dirname),
+        "--force",
+      ]);
+    },
+    clock: opts?.clock ?? SystemClock(),
+  };
+}

package/worktree-reaper.unit.test.ts

@@ -0,0 +1,380 @@
+/**
+ * agent/src/runtime/worktree-reaper.unit.test.ts
+ *
+ * Unit tests for reconcileStaleWorktrees() — a pure-filesystem background
+ * pass (WTR-1.2) that force-removes worktrees/ directories older than the
+ * configured cleanup_after_days threshold.
+ *
+ * Uses fully injected fs/git-exec/clock doubles — no real filesystem or git
+ * calls, no global.fetch/global.* overrides, time injected via FixedClock —
+ * per this repo's unit-test isolation contract.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { FixedClock } from "./clock.ts";
+import {
+  type RemoveWorktreeCall,
+  reconcileStaleWorktrees,
+  type WorktreeReaperDeps,
+} from "./worktree-reaper.ts";
+
+// ─── Fakes ────────────────────────────────────────────────────────────────────
+
+const FAKE_NOW = new Date("2026-07-28T00:00:00.000Z");
+
+interface MakeDepsOptions {
+  cleanupMergedWorktrees?: boolean;
+  cleanupAfterDays?: number;
+  dirs?: string[];
+  scopedRepos?: string[];
+  /** dirname -> mtime. Any dirname not present here throws (defensive — every test must configure the dirs it lists). */
+  mtimes?: Record<string, Date>;
+  /** dirname -> Error to throw from removeWorktree, if configured. */
+  removeErrors?: Record<string, Error>;
+  now?: Date;
+}
+
+function makeDeps(opts: MakeDepsOptions = {}): {
+  deps: WorktreeReaperDeps;
+  removeCalls: RemoveWorktreeCall[];
+} {
+  const {
+    cleanupMergedWorktrees = true,
+    cleanupAfterDays = 14,
+    dirs = [],
+    scopedRepos = [],
+    mtimes = {},
+    removeErrors = {},
+    now = FAKE_NOW,
+  } = opts;
+
+  const removeCalls: RemoveWorktreeCall[] = [];
+
+  const deps: WorktreeReaperDeps = {
+    readCleanupMergedWorktrees: async () => cleanupMergedWorktrees,
+    readCleanupAfterDays: async () => cleanupAfterDays,
+    listWorktreeDirs: () => dirs,
+    getScopedRepos: () => scopedRepos,
+    statMtime: (dirname: string) => {
+      const mtime = mtimes[dirname];
+      if (!mtime) {
+        throw new Error(`test fixture missing mtime for dirname: ${dirname}`);
+      }
+      return mtime;
+    },
+    removeWorktree: async (repo: string, dirname: string) => {
+      removeCalls.push({ repo, dirname });
+      const err = removeErrors[dirname];
+      if (err) throw err;
+    },
+    clock: FixedClock(now),
+  };
+
+  return { deps, removeCalls };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("reconcileStaleWorktrees", () => {
+  test("AC1: removes a worktree older than cleanup_after_days whose name's prefix matches a scoped repo", async () => {
+    // 20 days old, threshold 14 — stale.
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo-feat-foo"],
+      scopedRepos: ["example-repo"],
+      mtimes: { "example-repo-feat-foo": oldMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-foo" },
+    ]);
+  });
+
+  test("AC2: leaves a worktree younger than the threshold untouched", async () => {
+    // 2 days old, threshold 14 — not stale.
+    const recentMtime = new Date("2026-07-26T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo-feat-foo"],
+      scopedRepos: ["example-repo"],
+      mtimes: { "example-repo-feat-foo": recentMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([]);
+  });
+
+  test("AC3: cleanup_merged_worktrees false — no directories scanned or removed", async () => {
+    let listCalled = false;
+    let statCalled = false;
+    const { deps, removeCalls } = makeDeps({
+      cleanupMergedWorktrees: false,
+      dirs: ["example-repo-feat-foo"],
+      scopedRepos: ["example-repo"],
+      mtimes: { "example-repo-feat-foo": new Date("2020-01-01T00:00:00.000Z") },
+    });
+    const wrappedDeps: WorktreeReaperDeps = {
+      ...deps,
+      listWorktreeDirs: () => {
+        listCalled = true;
+        return deps.listWorktreeDirs();
+      },
+      statMtime: (dirname: string) => {
+        statCalled = true;
+        return deps.statMtime(dirname);
+      },
+    };
+
+    await reconcileStaleWorktrees(wrappedDeps);
+
+    expect(listCalled).toBe(false);
+    expect(statCalled).toBe(false);
+    expect(removeCalls).toEqual([]);
+  });
+
+  test("AC4: dirname whose prefix matches no scoped repo is skipped defensively", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["unknown-repo-feat-foo"],
+      scopedRepos: ["example-repo", "shipwright"],
+      mtimes: { "unknown-repo-feat-foo": oldMtime },
+    });
+
+    await expect(reconcileStaleWorktrees(deps)).resolves.toBeUndefined();
+    expect(removeCalls).toEqual([]);
+  });
+
+  test("AC5: a single directory's removeWorktree failure is caught and logged; remaining directories still processed", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo-feat-broken", "shipwright-feat-fine"],
+      scopedRepos: ["example-repo", "shipwright"],
+      mtimes: {
+        "example-repo-feat-broken": oldMtime,
+        "shipwright-feat-fine": oldMtime,
+      },
+      removeErrors: {
+        "example-repo-feat-broken": new Error("git worktree remove failed"),
+      },
+    });
+
+    await expect(reconcileStaleWorktrees(deps)).resolves.toBeUndefined();
+
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-broken" },
+      { repo: "shipwright", dirname: "shipwright-feat-fine" },
+    ]);
+  });
+
+  test("longest-prefix match: dashed repo names don't false-positive against a shorter prefix", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo-feat-foo"],
+      // "example" is a false-positive shorter prefix; "example-repo" is the real, longer match.
+      scopedRepos: ["example", "example-repo"],
+      mtimes: { "example-repo-feat-foo": oldMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-foo" },
+    ]);
+  });
+
+  test("dirname exactly equal to a scoped repo name matches", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo"],
+      scopedRepos: ["example-repo"],
+      mtimes: { "example-repo": oldMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo" },
+    ]);
+  });
+
+  test("a dirname that merely starts with a repo name's characters but not at a '-' boundary does not match", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      // "example-repository-feat-x" should NOT match scoped repo "example-repo" —
+      // the character after the prefix must be a "-" boundary (or nothing).
+      dirs: ["example-repository-feat-x"],
+      scopedRepos: ["example-repo"],
+      mtimes: { "example-repository-feat-x": oldMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([]);
+  });
+
+  test("uses the default cleanup_after_days (14) when the policy is at its default", async () => {
+    // 15 days old — stale under the 14-day default.
+    const staleUnderDefault = new Date("2026-07-13T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo-feat-foo"],
+      scopedRepos: ["example-repo"],
+      mtimes: { "example-repo-feat-foo": staleUnderDefault },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-foo" },
+    ]);
+  });
+
+  test("multiple stale directories across different repos are all removed", async () => {
+    const oldMtime = new Date("2026-07-01T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo-feat-a", "shipwright-feat-b", "example-repo-fix-c"],
+      scopedRepos: ["example-repo", "shipwright"],
+      mtimes: {
+        "example-repo-feat-a": oldMtime,
+        "shipwright-feat-b": oldMtime,
+        "example-repo-fix-c": oldMtime,
+      },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-a" },
+      { repo: "shipwright", dirname: "shipwright-feat-b" },
+      { repo: "example-repo", dirname: "example-repo-fix-c" },
+    ]);
+  });
+
+  test("a mix of stale, fresh, and unmatched directories only removes the stale+matched one", async () => {
+    const oldMtime = new Date("2026-07-01T00:00:00.000Z");
+    const recentMtime = new Date("2026-07-27T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: [
+        "example-repo-feat-stale",
+        "example-repo-feat-fresh",
+        "ghost-repo-feat-x",
+      ],
+      scopedRepos: ["example-repo"],
+      mtimes: {
+        "example-repo-feat-stale": oldMtime,
+        "example-repo-feat-fresh": recentMtime,
+        "ghost-repo-feat-x": oldMtime,
+      },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-stale" },
+    ]);
+  });
+
+  test("RCO-1.1: an org/repo scoped entry matches its corresponding bare-name worktree dirname", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["ok-wow-agency-feat-foo"],
+      scopedRepos: ["ok-wow/ok-wow-agency"],
+      mtimes: { "ok-wow-agency-feat-foo": oldMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    // The bare repo name ("ok-wow-agency"), not the raw "org/repo" string, is
+    // what's passed to removeWorktree — mirrors pr-state-reconciler.ts's own
+    // splitOrgRepo(record.repo) -> shortRepo usage for the same worktree path
+    // shape.
+    expect(removeCalls).toEqual([
+      { repo: "ok-wow-agency", dirname: "ok-wow-agency-feat-foo" },
+    ]);
+  });
+
+  test("RCO-1.1: bare-repo-name-only scoped entries (no slash) still match directly", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["shipwright-feat-bar"],
+      scopedRepos: ["shipwright"],
+      mtimes: { "shipwright-feat-bar": oldMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([
+      { repo: "shipwright", dirname: "shipwright-feat-bar" },
+    ]);
+  });
+
+  test("RCO-1.1: two org/repo entries from different orgs sharing the same bare repo name are treated as ambiguous — neither is matched", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["widget-feat-foo"],
+      scopedRepos: ["org-a/widget", "org-b/widget"],
+      mtimes: { "widget-feat-foo": oldMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    // Ambiguous — must NOT arbitrarily pick org-a or org-b's "widget".
+    expect(removeCalls).toEqual([]);
+  });
+
+  test("RCO-1.1: longest-match-wins still applies to the normalized (bare) name when an org/repo entry and a longer bare entry both match", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo-feat-foo"],
+      // "org/example" normalizes to "example" — a false-positive shorter
+      // prefix; "example-repo" (already bare) is the real, longer match.
+      scopedRepos: ["org/example", "example-repo"],
+      mtimes: { "example-repo-feat-foo": oldMtime },
+    });
+
+    await reconcileStaleWorktrees(deps);
+
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-foo" },
+    ]);
+  });
+
+  test("getScopedRepos is invoked live on each call — a repo added between two reconcile passes is picked up on the second pass without rebuilding deps", async () => {
+    const oldMtime = new Date("2026-07-08T00:00:00.000Z");
+    // Mutable backing array, mirroring agentReposRef.get()'s live-scope semantics.
+    let backingScopedRepos: string[] = ["example-repo"];
+    const { deps, removeCalls } = makeDeps({
+      dirs: ["example-repo-feat-foo", "shipwright-feat-bar"],
+      mtimes: {
+        "example-repo-feat-foo": oldMtime,
+        "shipwright-feat-bar": oldMtime,
+      },
+    });
+    const liveDeps: WorktreeReaperDeps = {
+      ...deps,
+      getScopedRepos: () => backingScopedRepos,
+    };
+
+    // First pass: "shipwright" is not yet in scope — its worktree is skipped.
+    await reconcileStaleWorktrees(liveDeps);
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-foo" },
+    ]);
+
+    // Scope changes out-of-band (e.g. syncConfig() adds a repo) between passes.
+    backingScopedRepos = ["example-repo", "shipwright"];
+
+    // Second pass against the SAME deps object: the live getter must reflect
+    // the mutation without deps being rebuilt/memoized. (The fake
+    // removeWorktree doesn't actually delete anything, so
+    // "example-repo-feat-foo" is still stale and removed again on this pass —
+    // the assertion only cares that "shipwright-feat-bar" is now included.)
+    await reconcileStaleWorktrees(liveDeps);
+    expect(removeCalls).toEqual([
+      { repo: "example-repo", dirname: "example-repo-feat-foo" },
+      { repo: "example-repo", dirname: "example-repo-feat-foo" },
+      { repo: "shipwright", dirname: "shipwright-feat-bar" },
+    ]);
+  });
+});

package/README.md

@@ -1,3 +0,0 @@
-# @app-vitals/agent-runtime
-
-Placeholder reserving this name. Real releases are published from https://github.com/app-vitals/agent.