@dsdenes/devboard 0.1.560 → 0.1.563

package/templates/host-AGENTS.md

@@ -0,0 +1,235 @@
+# AGENTS.md
+
+Two layers. Identify yours before reading or editing.
+
+```
+<repo root>/
+  .devboard/   <- harness: interface, prompts, wrappers, install.sh
+  adrs/        <- host data
+  GOAL.md      <- host data
+  .omp/        <- installed harness wrappers
+  ...          <- host project
+```
+
+| Path | Identity |
+| --- | --- |
+| `.devboard/` | Agentic development harness. Project-agnostic. Owns the browser interface and its toolchain. Works *on* the host. Never the host product. |
+| `.devboard/omp/` | Canonical agent wrappers; installed into the host's `.omp/`. |
+| `adrs/`, `GOAL.md` | Host data at the root; never harness artifacts. |
+| everything else | Host project. |
+
+## Containment boundary
+
+The whole project — host, harness, toolchain, tests, fixtures, caches, logs, temporary
+files, and worktrees — lives inside `<repo root>`. Nothing may be created, written, or kept
+outside it: not under `/tmp`, not in a home directory, not in a parent, sibling, or other
+checkout. This applies to every agent, script, and service, including throwaway
+verification, "safe" sandbox copies, and manual test data.
+
+- Point every path variable (`ADRS_DIR`, `REPO_DIR`, `GOAL_FILE`, `STATIC_DIR`) at a
+  location inside `<repo root>`.
+- When a tool defaults outside the root, override it to a directory inside the root; never
+  accept the default.
+- Asked to place a file, artifact, cache, log, or worktree outside the root? Refuse and
+  propose the in-repo path.
+- Running system binaries (`bun`, `git`, `gh`, `omp`) is not a violation; writing their
+  output outside the root is.
+
+A temporary directory is still project data. Create it under `<repo root>` (for example
+under `.worktree/`), never outside.
+
+## Scope
+
+Default to the host project. "the repo", "the project", "the code", and unnamed files all mean the host project.
+
+Enter harness mode only when the request names the harness, "devboard", or a path inside `.devboard/`.
+
+| Mode | Trigger | Edit |
+| --- | --- | --- |
+| host (default) | everything else | host project; leave `.devboard/` untouched |
+| harness | explicit harness / `.devboard` reference | `.devboard/` only; host files untouched unless named |
+
+A request naming both layers is two scopes; change each side by its own rules.
+Never edit `.devboard/` for a host request. Never edit host files for a harness request. If a task couples them, surface it and state the scope change.
+
+## Harness rules
+
+1. **Containment.** Keep every harness file inside `.devboard/`: code, scripts, prompts, tests, fixtures, docs, configs, CI glue, artifacts. Nothing harness-related is created outside `<repo root>` — no temporary files, caches, logs, or test data. Asked to place one outside? Refuse; propose the `.devboard/` path. Host files *invoking* the harness at runtime are fine.
+2. **Portability.** Harness code moves between unrelated hosts. Bake in nothing host-specific: no absolute paths, project names, identifiers, remotes, secrets, language/layout/build/test-runner assumptions. Discover host facts at runtime, take them as arguments, or read them from config under `.devboard/`. Emit host paths relative to the repo root.
+3. **Fixed location, fixed name.** Install at `<repo root>/.devboard`, spelled exactly that. Never rename or relocate per host.
+4. **Host-neutral deletion.** Deleting `.devboard/` must leave host build, tests, and run paths working. No host hard-dependency on the harness beyond `.devboard/` itself.
+5. **The one exception.** `AGENTS.md` sits at the repo root by design: agents must find it there. Host-agnostic, copied verbatim between hosts, not a harness artifact. Nothing else gets this treatment.
+
+## Interface
+
+`.devboard/` owns the browser interface and everything needed to build, test, and run it: the Bun
+server, the Svelte client, the tests and fixtures, `package.json`, `bun.lock`, the build
+configuration, `index.html`, the `Dockerfile`, and `README.md`. Run its commands from `.devboard`:
+`bun install`, `bun test`, `bun run build`, `bun run start`; build the container from the
+`.devboard` context. The interface is a harness tool, not the host product.
+
+The harness may define its own toolchain, but it must not assume host facts: no host language,
+package manager, test runner, build system, or layout. Host data lives at the root — the decision
+records in `adrs/` and the goal document `GOAL.md` — and reaches the interface only through paths
+the host supplies: `ADRS_DIR`, `REPO_DIR`, `GOAL_FILE`, `STATIC_DIR`, `AGENT_COMMAND`. The
+lifecycle prompts under `.devboard/prompts/` likewise treat the repository root as the host and
+exclude `.devboard/` and `.worktree/` from every survey and every write.
+
+## Releases and installation
+
+The harness is the public npm package `@dsdenes/devboard`. One tarball carries the launcher, the
+server, the client sources and built bundle, the prompts, the omp wrappers and extensions, the
+templates, and the installer. npm is the authority for install and update versions and artifacts;
+no local checkout, running dashboard, or required release tarball is involved. GitHub is only a
+push mirror of this repository; it carries no release the dashboard reads.
+
+A host installs a real npm prefix at `<host>/.devboard` with
+`npx @dsdenes/devboard install`. `<host>/.omp/commands`, `<host>/.omp/extensions`, and
+`<host>/AGENTS.md` are real copies from the installed package; no harness path is a symlink.
+The canonical `.devboard/` in this checkout is the source tree and is never an npm install.
+
+Every running dashboard checks the newest npm version at startup and every 60 seconds, installs a
+newer artifact, and keeps serving the version it loaded. It reports `versionState` (`running`,
+`installed`, `latest`, `stale`) and shows the reload control while `stale` is true. Only clicking
+that control restarts the server from the installed package and reloads the page. When npm cannot
+resolve or serve the artifact and `DEVBOARD_GITEA_URL` is configured, install and update fall back
+to the Gitea release tarball and its `.sha256` for the same version. A failed download, checksum,
+authentication, or install leaves the installed package and the running server intact; the
+journal records the failure and doctor reports it.
+
+Harness-owned issue reporting uses only the configured Gitea API. Without `DEVBOARD_GITEA_URL`
+the report controls are not rendered and `POST /api/feedback` answers HTTP 503 naming that
+variable; no GitHub request is made. Host-forge behavior for GitHub, GitLab, and Gitea origins is
+unchanged.
+
+## Publish after every change
+
+Publishing is a release, not a restart. Merging into `main` and pushing triggers the
+`.gitea/workflows/devboard-release.yml` workflow, which builds, tests, packs the complete public
+package, publishes `@dsdenes/devboard@<version>` to npmjs, and creates the Gitea release with
+notes plus the same tarball and its `.sha256` as a fallback. Nothing is published under
+`@dsdenes/devboard-harness`.
+
+A change is not finished until the workflow for the pushed commit succeeds, the npm package and
+Gitea release assets exist, and the installed hosts have picked the release up. After the push, run
+from the integration checkout — never from a worktree:
+
+```bash
+cd .devboard
+bun run publish
+```
+
+`bun run publish` is the verification path. It:
+
+1. refuses a worktree, a branch other than `main`, or a checkout ahead of or diverged from its
+   canonical remote;
+2. fetches the remote and fast-forwards `main` to it; uncommitted work is never discarded — an
+   overlapping local change stops the run and names the blocking paths;
+3. runs `bun install --frozen-lockfile` and `bun run build`, then proves `dist/index.html` is
+   newer than every client source and that every referenced asset exists;
+4. waits for the `devboard-release.yml` run of `HEAD` and requires a successful conclusion;
+5. verifies the npm package and the Gitea release's fallback tarball and `.sha256`;
+6. pushes the `github` mirror remote and proves its `main` names the published commit;
+7. reports every running dashboard's running and installed versions without restarting it.
+
+Options: `--wait-timeout N` bounds the workflow and propagation wait (default 1800 seconds).
+It never restarts a dashboard, never writes into a host, and exits nonzero when the npm package
+or the release assets are missing. Installed dashboards update themselves; an operator clicks the
+reload control when they want the new code.
+
+The integration checkout is advanced and rebuilt after a push; it is never a place for feature
+work. If its uncommitted changes block the fast-forward, preserve them (copy or patch them
+aside, apply the published revision, reapply the changes) and rerun `publish`. Never discard
+them and never bypass the fast-forward.
+
+Guardrails:
+
+- Never rebuild only a worktree or only the client and call the change done.
+- Never kill, spawn, or relaunch a dashboard server by hand; install, update, and the reload
+  control are the only paths.
+- Never copy the harness into a host or symlink a host path to this checkout; install owns the
+  host prefix.
+- Stale output is the first suspect, not the last: when the UI behaves like an older revision,
+  compare `versionState` and the installed package version before debugging client code.
+- A UI check against a bundle or server older than the changed source is not a passing
+  verification.
+
+## Wrappers
+
+`.devboard/omp/` is canonical: agent commands live in `omp/commands/` and extensions in
+`omp/extensions/`, never in the root `.omp/`. `.devboard/install.sh` copies every file under
+`.devboard/omp/` to the same relative path under `<host>/.omp/`. The host path is an argument or
+is discovered with `git rev-parse --show-toplevel`; the script refuses a host without a
+`.devboard/` directory, refuses to overwrite a differing file without `--force`, never touches
+unrelated files, and is safe to rerun. Edit `.devboard/omp/`, rerun `install.sh`, and never
+hand-edit the installed `.omp/`.
+
+## Cross-boundary changes
+
+Split, never mix: host-specific detail in host files; generic mechanism in `.devboard/` taking that detail as input. A host name, path, or stack inside `.devboard/` is a bug. A harness dependency outside it is a bug.
+
+## Worktree
+
+Do all work — host and harness — in an isolated git worktree: `<repo root>/.worktree/<name>`.
+Never outside the repo root. Never edit the opened checkout. One worktree per task; edit, build,
+and test inside it.
+
+Done means merged into main **and pushed to the upstream that tracks it**. A local commit, a local
+merge, or a deleted worktree branch is not done. Before deleting the worktree, verify the push:
+`git ls-remote <remote> refs/heads/main` must name the integration commit, and
+`git status --short --branch` must report no commits ahead of the upstream. A local merge that is
+never pushed is a failed task, even when every test passes. If a push is rejected, fetch the new
+tip, integrate it, resolve every conflict yourself, rerun the checks it invalidates, and push
+again. Never finish, hand off, or delete the worktree with local-only changes.
+
+After the push, advance the integration checkout to the published revision without discarding
+its uncommitted work, then run `cd .devboard && bun run publish` so every dashboard that serves
+the checkout runs the new bundle and server. Deleting the worktree before the integration
+checkout is published and verified is a failed task.
+
+## Line length
+
+Never create a line longer than 768 bytes (UTF-8) in a repository text file. Hard-wrap
+prose, prompts, and Markdown list items; do not rely on a later reader re-opening a
+truncated line. Aim for 100 columns or less. Generated files such as lockfiles are exempt;
+never hand-edit them.
+
+## Working rules
+
+- State mode and edit root before the first edit.
+- Decide which side a new file belongs on first. Two common bugs: a harness artifact in host code, a host fact baked into `.devboard/`.
+- Run harness work from the repo root with the host path passed in or discovered at runtime.
+- In harness mode, never "temporarily" write outside `.devboard/`; fix the layering.
+- Host mode leaves `.devboard/` byte-identical. Harness mode leaves host behavior unchanged except where asked.
+- Pushing is part of the task, not a follow-up. Never stop with a commit or merge that exists only
+  locally, even when every test passes and the worktree is clean.
+
+## Done
+
+- Both modes: done in `.worktree/<name>`, merged to main, pushed to the canonical upstream, and
+  verified that the upstream tip is the integrated commit. Only then are the worktree and branch
+  removed. Local-only main is never done.
+- Host mode: host build/tests run; `.devboard/` unchanged.
+- Harness mode: the pushed commit's release workflow succeeded and `bun run publish` verified
+  the npm package and release assets; installed dashboards report the release through
+  `versionState` and restart only from the reload control; the changed entry point runs from the
+  repo root against a supplied host path; no absolute paths or host specifics under
+  `.devboard/`; nothing created outside `.devboard/`.
+
+## Map
+
+- `.devboard/` — harness root: interface, toolchain, prompts, extensions, goals, tests,
+  `omp/`, `install.sh`, `scripts/publish.ts`.
+- `.devboard/scripts/publish.ts` — verifies `main`, waits for the release workflow, proves the
+  npm package and release assets, and reports dashboards without restarting them.
+- `.devboard/scripts/release.ts` — publishes the public package and the Gitea fallback release.
+- `.devboard/templates/host-AGENTS.md` — host contract copied at release time; byte-identical to
+  this file.
+- `.gitea/workflows/devboard-release.yml` — CI on the canonical Gitea instance: install, build,
+  test, typecheck, and release. GitHub receives a push mirror only.
+- `.devboard/omp/` — canonical agent commands and extensions.
+- `.omp/` — installed copy of `.devboard/omp/`; never edited by hand.
+- `adrs/`, `GOAL.md` — host data at the root; not harness artifacts.
+- `.devboard/AGENTS.md` — harness-internal instructions, when present.
+- `.worktree/` — per-task worktrees; ephemeral.
+- `AGENTS.md` — harness ⇄ host contract; at repo root by design.

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "types": ["bun"],
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  },
+  "include": [
+    "client/**/*.ts",
+    "client/**/*.d.ts",
+    "client/**/*.svelte",
+    "server/**/*.ts",
+    "issues/**/*.ts",
+    "vite.config.ts"
+  ]
+}

package/vite.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [tailwindcss(), svelte()],
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+    chunkSizeWarningLimit: 12000,
+    rollupOptions: {
+      output: {
+        manualChunks(id: string) {
+          if (id.includes("monaco-editor")) return "monaco";
+          if (id.includes("@xterm")) return "xterm";
+          return undefined;
+        },
+      },
+    },
+  },
+});

package/watchdog/cleanup-main.ts

@@ -0,0 +1,98 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { runCleanup } from "./cleanup";
+import { discoverInstances } from "./discovery";
+
+/**
+ * `bun run cleanup -- --dry-run` prints one week's retention plan for every
+ * covered state directory; `--once` applies it. The watchdog cycle performs
+ * the same sweep; this entry point exists for operators and verification.
+ */
+
+const usage = `Usage: bun run cleanup [options]
+
+Removes entries older than seven days from every devboard state directory the
+watchdog covers: the canonical checkout, its direct siblings, and live
+dashboards. Journal retention stays with the journal.
+
+  --once             Delete every eligible entry. The default is dry-run.
+  --dry-run          Print the plan and change nothing.
+  --root <path>      Canonical repository root. Defaults to this checkout.
+  -h, --help         Show this text.
+`;
+
+const args = process.argv.slice(2);
+let once = false;
+let dryRun = false;
+let rootOption: string | undefined;
+
+for (let index = 0; index < args.length; index += 1) {
+  const argument = args[index];
+  if (argument === "--once") once = true;
+  else if (argument === "--dry-run") dryRun = true;
+  else if (argument === "--root") {
+    rootOption = args[index + 1];
+    index += 1;
+    if (rootOption === undefined) {
+      console.error("cleanup: --root needs a path");
+      process.exit(2);
+    }
+  } else if (argument === "-h" || argument === "--help") {
+    console.log(usage);
+    process.exit(0);
+  } else {
+    console.error(`cleanup: unknown option ${argument}`);
+    console.error(usage);
+    process.exit(2);
+  }
+}
+
+if (once && dryRun) {
+  console.error("cleanup: --once and --dry-run are exclusive");
+  process.exit(2);
+}
+
+function gitTopLevel(): string {
+  const result = Bun.spawnSync({
+    cmd: ["git", "-C", dirname(import.meta.dir), "rev-parse", "--show-toplevel"],
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const top = result.stdout.toString().trim();
+  if (result.exitCode !== 0 || top.length === 0) {
+    console.error("cleanup: the harness is not inside a git checkout");
+    process.exit(2);
+  }
+  return top;
+}
+
+const root = resolve(rootOption ?? gitTopLevel());
+if (!existsSync(join(root, ".devboard"))) {
+  console.error(`cleanup: missing prerequisite: ${join(root, ".devboard")} does not exist`);
+  process.exit(2);
+}
+
+const instances = discoverInstances({ selfPids: new Set([process.pid]) });
+const report = runCleanup({ root, instances, dryRun: dryRun || !once });
+const effectiveDryRun = dryRun || !once;
+const verb = effectiveDryRun ? "would remove" : "removed";
+let errors = 0;
+
+for (const entry of report.roots) {
+  console.log(
+    `cleanup: ${entry.stateDir}: ${verb} ${entry.files} file(s), ` +
+      `${entry.directories} directory/directories, ${entry.bytes} byte(s)`,
+  );
+  if (effectiveDryRun) {
+    for (const candidate of entry.candidates) {
+      console.log(`  ${candidate.kind} ${candidate.path} ${candidate.bytes}`);
+    }
+  }
+  for (const error of entry.errors) {
+    errors += 1;
+    console.error(`cleanup: ${entry.stateDir}: ${error}`);
+  }
+}
+
+process.exit(errors === 0 ? 0 : 1);

package/watchdog/cleanup.ts

@@ -0,0 +1,301 @@
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  realpathSync,
+  rmdirSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { ISSUES_DIRECTORY } from "../issues/paths";
+import { JOURNAL_RETENTION_MS } from "../server/journal";
+
+/**
+ * Age-based retention for everything a devboard state directory accumulates.
+ * The journal keeps its own rule in `server/journal.ts`; this module sweeps the
+ * rest of `.tmp`: run directories, loop logs, legacy dashboard files, and
+ * verification scratch. Nothing here decides what a dashboard should keep.
+ */
+
+/** The one-week threshold; the journal uses the same number. */
+export const CLEANUP_RETENTION_MS = JOURNAL_RETENTION_MS;
+
+export type CleanupSource = "canonical" | "sibling" | "instance";
+
+export interface CoveredStateDir {
+  stateDir: string;
+  source: CleanupSource;
+}
+
+export interface CleanupCandidate {
+  path: string;
+  bytes: number;
+  kind: "file" | "symlink" | "directory";
+}
+
+export interface CleanupRootReport {
+  stateDir: string;
+  source: CleanupSource;
+  /** Everything eligible under this directory, whether or not it was removed. */
+  candidates: CleanupCandidate[];
+  /** What the run removed; empty in a dry run. */
+  removed: CleanupCandidate[];
+  /** Bytes removed, or bytes a dry run would remove. */
+  bytes: number;
+  files: number;
+  directories: number;
+  errors: string[];
+}
+
+export interface CleanupReport {
+  now: string;
+  cutoff: string;
+  dryRun: boolean;
+  roots: CleanupRootReport[];
+}
+
+export interface CleanupInstance {
+  stateDir?: string;
+  journal: string;
+}
+
+export interface CleanupRunOptions {
+  root: string;
+  now?: Date;
+  dryRun?: boolean;
+  instances?: CleanupInstance[];
+  /** Test seam: replace discovery outright. */
+  covered?: CoveredStateDir[];
+  /** The watchdog run directory of the cycle performing the sweep. */
+  watchdogRunDir?: string;
+}
+
+function stateDirectory(instance: CleanupInstance): string {
+  return instance.stateDir ?? dirname(dirname(instance.journal));
+}
+
+function realDirectory(path: string): string | undefined {
+  try {
+    if (!lstatSync(path).isDirectory()) return undefined;
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The state directories one sweep covers: the canonical harness, every direct
+ * sibling `<host>/.devboard/.tmp`, and every live dashboard's real state
+ * directory (derived from its journal, never from the serving package).
+ * De-duplicated by real path; a symlinked `.tmp` is never followed.
+ */
+export function coveredStateDirs(
+  root: string,
+  instances: CleanupInstance[] = [],
+): CoveredStateDir[] {
+  const covered: CoveredStateDir[] = [];
+  const seen = new Set<string>();
+  const add = (path: string, source: CleanupSource): void => {
+    const real = realDirectory(path);
+    if (real === undefined || seen.has(real)) return;
+    seen.add(real);
+    covered.push({ stateDir: real, source });
+  };
+
+  add(join(root, ".devboard", ".tmp"), "canonical");
+
+  let names: string[] = [];
+  try {
+    names = readdirSync(dirname(root)).sort();
+  } catch {
+    names = [];
+  }
+  for (const name of names) {
+    add(join(dirname(root), name, ".devboard", ".tmp"), "sibling");
+  }
+  for (const instance of instances) add(stateDirectory(instance), "instance");
+
+  return covered;
+}
+
+/** True when a lock file's name records a pid that is still alive. */
+function liveLegacyLock(path: string): boolean {
+  const match = /^devboard-(\d+)\.lock$/.exec(path.slice(path.lastIndexOf(sep) + 1));
+  if (match === null) return false;
+  return existsSync(`/proc/${match[1]}`);
+}
+
+function inside(directory: string, path: string): boolean {
+  const rest = relative(directory, path);
+  return rest.length > 0 && rest !== ".." && !rest.startsWith(`..${sep}`) && !rest.startsWith(sep);
+}
+
+interface SweepOptions {
+  now: Date;
+  dryRun: boolean;
+  watchdogRunDir?: string;
+}
+
+/**
+ * One state directory. Every file or symlink older than the cutoff is a
+ * candidate; a directory is one when it would be empty and its own mtime, read
+ * before any deletion, is older. Protected paths are never even descended into.
+ */
+export function sweepStateDir(
+  stateDir: string,
+  options: SweepOptions,
+): CleanupRootReport {
+  const cutoff = options.now.getTime() - CLEANUP_RETENTION_MS;
+  const errors: string[] = [];
+  const candidates: CleanupCandidate[] = [];
+  const report: CleanupRootReport = {
+    stateDir,
+    source: "canonical",
+    candidates,
+    removed: [],
+    bytes: 0,
+    files: 0,
+    directories: 0,
+    errors,
+  };
+
+  const info = realDirectory(stateDir);
+  if (info === undefined) {
+    errors.push("not a directory; nothing swept");
+    return report;
+  }
+  const directory = info;
+  const protectedPrefixes = [
+    join(directory, "state"),
+    join(directory, "journal"),
+    // Every repo-scoped issues record: state, ledger, runs, activity, control,
+    // and the repo-anchored lock a worker holds. A running worker's run
+    // directory is therefore never swept.
+    join(directory, ISSUES_DIRECTORY),
+    // Flow session records: machine state, reviewable artifacts, and the
+    // worktree/PR bookkeeping Flow restore and History read. Nothing
+    // recreates a swept session, so an untouched one must survive.
+    join(directory, "flow"),
+    ...(options.watchdogRunDir === undefined ? [] : [resolve(options.watchdogRunDir)]),
+  ];
+  const protectedExact = new Set([
+    join(directory, "watchdog", "state.json"),
+    join(directory, "watchdog", "latest.json"),
+    join(directory, "watchdog", "lock"),
+    join(directory, "orchestrator", "state.json"),
+    join(directory, "orchestrator", "ledger.json"),
+    join(directory, "orchestrator", "lock"),
+  ]);
+
+  const isProtected = (path: string): boolean => {
+    if (protectedExact.has(path)) return true;
+    if (liveLegacyLock(path)) return true;
+    return protectedPrefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}${sep}`));
+  };
+
+  const visit = (path: string): { removable: boolean; bytes: number } => {
+    if (isProtected(path)) return { removable: false, bytes: 0 };
+    let entry;
+    try {
+      entry = lstatSync(path);
+    } catch (error) {
+      errors.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+      return { removable: false, bytes: 0 };
+    }
+    if (entry.isSymbolicLink()) {
+      if (entry.mtimeMs < cutoff) {
+        candidates.push({ path, bytes: 0, kind: "symlink" });
+        return { removable: true, bytes: 0 };
+      }
+      return { removable: false, bytes: 0 };
+    }
+    if (entry.isFile()) {
+      if (entry.mtimeMs < cutoff) {
+        candidates.push({ path, bytes: entry.size, kind: "file" });
+        return { removable: true, bytes: entry.size };
+      }
+      return { removable: false, bytes: 0 };
+    }
+    if (!entry.isDirectory()) return { removable: false, bytes: 0 };
+
+    let names: string[] = [];
+    try {
+      names = readdirSync(path).sort();
+    } catch (error) {
+      errors.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+      return { removable: false, bytes: 0 };
+    }
+    let survivors = 0;
+    let bytes = 0;
+    for (const name of names) {
+      const child = visit(join(path, name));
+      bytes += child.bytes;
+      if (!child.removable) survivors += 1;
+    }
+    if (survivors === 0 && entry.mtimeMs < cutoff) {
+      candidates.push({ path, bytes: 0, kind: "directory" });
+      return { removable: true, bytes };
+    }
+    return { removable: false, bytes };
+  };
+
+  let top: string[] = [];
+  try {
+    top = readdirSync(directory).sort();
+  } catch (error) {
+    errors.push(`${directory}: ${error instanceof Error ? error.message : String(error)}`);
+    return report;
+  }
+  for (const name of top) visit(join(directory, name));
+
+  let bytes = 0;
+  for (const candidate of candidates) bytes += candidate.bytes;
+  if (options.dryRun) {
+    report.bytes = bytes;
+    report.files = candidates.filter((candidate) => candidate.kind !== "directory").length;
+    report.directories = candidates.filter((candidate) => candidate.kind === "directory").length;
+    return report;
+  }
+
+  for (const candidate of candidates) {
+    if (!inside(directory, candidate.path)) {
+      errors.push(`${candidate.path}: refuses to delete outside ${directory}`);
+      continue;
+    }
+    try {
+      if (candidate.kind === "directory") rmdirSync(candidate.path);
+      else unlinkSync(candidate.path);
+      report.removed.push(candidate);
+      report.bytes += candidate.bytes;
+      if (candidate.kind === "directory") report.directories += 1;
+      else report.files += 1;
+    } catch (error) {
+      errors.push(
+        `${candidate.path}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  return report;
+}
+
+/** Finds every covered state directory and sweeps each one. */
+export function runCleanup(options: CleanupRunOptions): CleanupReport {
+  const now = options.now ?? new Date();
+  const dryRun = options.dryRun === true;
+  const covered = options.covered ?? coveredStateDirs(options.root, options.instances ?? []);
+  const roots = covered.map((entry) => {
+    const report = sweepStateDir(entry.stateDir, {
+      now,
+      dryRun,
+      ...(options.watchdogRunDir === undefined ? {} : { watchdogRunDir: options.watchdogRunDir }),
+    });
+    report.source = entry.source;
+    return report;
+  });
+  return {
+    now: now.toISOString(),
+    cutoff: new Date(now.getTime() - CLEANUP_RETENTION_MS).toISOString(),
+    dryRun,
+    roots,
+  };
+}