viewable-one 0.0.0-stage → 0.12.1

package/lib/spawn.mjs

@@ -0,0 +1,330 @@
+// What a spawn REQUEST is, and the pure rules a request has to pass -
+// unchanged in shape since the file contract retired (brief 30 Move 2b,
+// 2026-09-11): `run.request` on a row carries exactly what `<id>.json`
+// carried, and `checkRequest`/`titleFor`/`wallClockFor`/`kindOf` are the
+// same functions either way, so `bridge/lib/runner.mjs` imports them
+// unchanged.
+//
+// listRequests remains for the sweep's historical request cleanup.
+// Runner presence is stored in rows; RUNNER_STALE_MS and RUNNER_BEAT_MS
+// still govern the live heartbeat and its diagnostic staleness window.
+
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { problems } from "./refusal.mjs";
+import { SPAWN_DIR as SPAWN_PATH, segmentsOf } from "./paths.mjs";
+import { SIGN_IN_AGENTS } from "./signIn.mjs";
+
+// Re-exported from paths.mjs so there is one definition of where the
+// runner's local scratch lives.
+export const SPAWN_DIR = join(...segmentsOf(SPAWN_PATH));
+
+/** THE SAME PLACE, SPELLED FOR A PERSON. `SPAWN_DIR` above is `join`ed, so
+ * on Windows it is `.glytch\inbox\spawn`; this is the `/`-spelled form for
+ * anything that prints the path to a human. */
+export const SPAWN_DIR_IN_WORDS = SPAWN_PATH;
+
+// A session left running all night bills all night, so there is a default and
+// a hard cap, and the cap is what a request may ask for.
+//
+// 90 minutes is still well under the 2-hour cap, still ends the night, and
+// still notices a hang before the invoice does. The board cannot override it:
+// buildSpawnRequest leaves maxMs out deliberately (src/folder/spawnRequest.ts:202),
+// so this constant IS the wall clock for everything filed from the canvas.
+export const DEFAULT_WALL_MS = 90 * 60_000;
+export const MAX_WALL_MS = 2 * 60 * 60_000;
+
+/** The terminal receipt's suffix - still meaningful locally: it is the
+ *  window `bridge/lib/sweep.mjs` uses to decide a finished request's age on
+ *  disk before this pass, and the file it names is written by nothing any
+ *  more (a row's `result` lives in Postgres) - so a folder swept after Move
+ *  2 finds none, which is the correct, quiet answer. */
+export const RECEIPT_SUFFIX = ".result.txt";
+
+/** Historical request ids in this folder's local scratch, sorted by name.
+ * The sweep uses these to find old receipts and server records. Dotfiles,
+ * including a heartbeat left by an old runner, are never requests. */
+export async function listRequests(root) {
+  let names;
+  try {
+    names = await readdir(join(root, SPAWN_DIR));
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => n.endsWith(".json") && !n.startsWith("."))
+    .map((n) => n.slice(0, -5))
+    .sort();
+}
+
+// Presence lives in runner_projects rows; the watcher beats every ten seconds
+// and a timestamp older than thirty seconds is stale.
+export const RUNNER_STALE_MS = 30_000;
+export const RUNNER_BEAT_MS = RUNNER_STALE_MS / 3;
+// A 0.12 runner joined to its push topic beats every 5 minutes (#813), and
+// the app gives it 6. Doctor runs beside a runner of its own version, so it
+// uses this window too.
+export const RUNNER_PUSH_STALE_MS = 6 * 60_000;
+
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+
+// ---------- WHICH KIND OF REQUEST (brief 25, session 1, 2026-09-07) ----------
+//
+// A request carries one field, `kind`, and it has exactly two values.
+// ABSENT MEANS "session", which is the whole compatibility story: every
+// request written before today - and every request the idea path
+// writes after it - has no `kind` and runs down the same code it always did,
+// byte for byte. This is the same rule `agent` and `resumeSessionId` already
+// follow.
+//
+// A `chat-turn` is a DM with a coding agent answered by the daemon (his
+// ruling 1A). It differs from a session in five ways and no others: no
+// idea on the board, no worktree minted per message, no repo primer and no
+// attempts log, a per-ROOM lock instead of the per-idea one, and (over
+// rows, brief 30 Move 2b) no other marker at all - the row's own
+// `request.kind` says which it is, where the file contract needed a `chat`
+// word on the receipt's own first line for a person reading it by eye. See
+// bridge/SPAWN.md, "Chat turns".
+export const SESSION_KIND = "session";
+export const CHAT_TURN_KIND = "chat-turn";
+// Sign in to an agent on this computer (#482, lib/signIn.mjs): no prompt,
+// no worktree, no model turn.
+export const SIGN_IN_KIND = "sign-in";
+export const REQUEST_KINDS = [SESSION_KIND, CHAT_TURN_KIND, SIGN_IN_KIND];
+
+/** The kind this request is, with the absent field read as "session". Spelled
+ * once, here, because "absent means session" is a compatibility promise and
+ * two spellings of it is how a promise like that stops being kept. */
+export const kindOf = (request) => {
+  const raw = typeof request?.kind === "string" ? request.kind.trim() : "";
+  return raw === "" ? SESSION_KIND : raw;
+};
+
+export const isChatTurn = (request) => kindOf(request) === CHAT_TURN_KIND;
+export const isSignIn = (request) => kindOf(request) === SIGN_IN_KIND;
+
+// ---------- PLAN MODE: which engines ----------
+//
+// briefs/plan-mode-beyond-claude.md. An engine belongs on this list only
+// once its draft path has been checked to enforce the required contract
+// (block project writes, board mutation, network escape and permission
+// escalation) rather than merely being told not to - see the note beside
+// its check in checkRequest below for what was verified for each name here.
+//
+// SINGLE-USE APPROVAL (contract point 4) is not this file's job any more:
+// there is no exclusive-create-on-disk to bind an approval to at most one
+// implementation the way `<id>.plan-consumed` did before the file contract
+// retired (brief 30 Move 2). `bridge/lib/runner.mjs`'s own execute branch
+// scans `runnerApi.runs` for another execute row already claimed against
+// the same `approvedPlanFrom` instead - see the comment there.
+export const PLAN_MODE_AGENTS = ["claude", "codex"];
+
+// One folder name, safe on every platform a runner runs on: no separators,
+// nothing Windows refuses (CON, NUL and the like included), no leading dot (hidden, and "." and ".."), no
+// trailing dot or space (Windows drops them). The app's boardFolderName
+// (src/runs/chatFolder.ts) writes names that pass.
+export const isBoardFolderName = (name) =>
+  typeof name === "string" && name.length >= 1 && name.length <= 80 &&
+  !/[/\\<>:"|?*]|^\.|[. ]$/.test(name) && ![...name].some((c) => c.charCodeAt(0) < 32) &&
+  !/^(con|prn|aux|nul|com\d|lpt\d)(\..*)?$/i.test(name);
+
+/** Every problem with a request, in one pass, in the bridge's refusal voice.
+ *
+ * `approved` is checked here rather than at the point of spawn on purpose: a
+ * request nobody approved must be refused by whatever first looks at it, not
+ * by the one code path that happens to run last. */
+export function checkRequest(request) {
+  const found = problems();
+  if (!isRecord(request)) {
+    found.note(
+      `A spawn request must be a JSON object like {"prompt": "...", "approved": true}, got ${Array.isArray(request) ? "an array" : typeof request}.`,
+    );
+    return found.list;
+  }
+  if (isSignIn(request)) {
+    if (!SIGN_IN_AGENTS.includes(request.agent)) found.note(`A sign-in request names agent ${SIGN_IN_AGENTS.join(" or ")}.`);
+  } else if (typeof request.prompt !== "string" || request.prompt.trim() === "") {
+    found.note('Pass prompt: what the session is being asked to do. It is the whole point of the request.');
+  }
+  if (request.approved !== true) {
+    found.note(
+      'This request is not approved, so it will never be run. A spawned session uses your own Claude Code or Codex plan, so "approved": true has to be set by a human gesture - never by the actor writing the request.',
+    );
+  }
+  if (request.planMode !== undefined) {
+    if (!["draft", "execute"].includes(request.planMode)) found.note("Unknown planMode. Use draft or execute.");
+    if (request.kind !== undefined) found.note("Plan mode is only available for prompt sessions.");
+    // WHICH ENGINES CAN ENFORCE READ-ONLY DRAFTING, checked against each
+    // engine's own CLI rather than assumed (briefs/plan-mode-beyond-claude.md).
+    // Claude Code: a restricted --allowedTools list plus --strict-mcp-config
+    // with an empty server map (commandFor's draft branch, agents.mjs).
+    // Codex: the native app-server's `sandbox: "read-only"` thread policy,
+    // which the generated protocol schema (`codex app-server
+    // generate-json-schema`) shows defaults `networkAccess: false` on top of
+    // the filesystem restriction, combined with never configuring the board
+    // MCP server for that thread's process at all (codex.mjs). opencode is
+    // deliberately absent: its shipped `plan` agent denies the structured
+    // `edit` tool but leaves `bash` on its default wildcard allow rule
+    // (`opencode agent list`), so a plan-mode session there could still
+    // write files or reach the network through a shell call - not
+    // enforceable from this bridge's side of the interface.
+    if (!PLAN_MODE_AGENTS.includes(request.agent ?? "claude")) {
+      found.note("Read-only plan approval currently requires Claude Code or Codex.");
+    }
+    if (request.planMode === "draft" && request.resumeSessionId) found.note("Plan mode must start a fresh session; resuming could carry implementation permissions.");
+    if (request.planMode === "execute" && (
+      typeof request.approvedPlan !== "string" || !request.approvedPlan.trim() ||
+      typeof request.approvedPlanFrom !== "string" || !/^spawn-[a-z0-9-]+$/.test(request.approvedPlanFrom) ||
+      request.approvedBy !== "board" || typeof request.approvedAt !== "string"
+    )) found.note("Implementation requires the human-approved plan, its completed draft request, and a board approval.");
+  } else if (request.approvedPlan !== undefined || request.approvedPlanFrom !== undefined) {
+    found.note("An approved plan must use planMode execute.");
+  }
+  if (request.title !== undefined && (typeof request.title !== "string" || request.title.trim() === "")) {
+    found.note("title, when present, names the session's frame on the board and must be a non-empty string.");
+  }
+  if (request.cwd !== undefined && (typeof request.cwd !== "string" || request.cwd.trim() === "")) {
+    found.note("cwd, when present, is the absolute directory to run in and must be a non-empty string.");
+  }
+  // WHICH KIND. Absent means "session" (kindOf above), so nothing written
+  // before today can fail this. A kind this runner has never heard of IS
+  // refused, and that is deliberate and the opposite of the `agent` rule
+  // below: an unknown engine name falls back to the default because running
+  // on the wrong engine beats dying while holding a claim, whereas an unknown
+  // KIND names a code path that does not exist here - there is nothing to
+  // fall back to, and guessing "session" would put a circle on his board for
+  // a request that asked for something else.
+  if (request.kind !== undefined) {
+    const kind = typeof request.kind === "string" ? request.kind.trim() : "";
+    if (!REQUEST_KINDS.includes(kind)) {
+      found.note(
+        `kind, when present, is ${REQUEST_KINDS.map((k) => `"${k}"`).join(" or ")}, got ${JSON.stringify(request.kind)}. Leave it out for an ordinary session: absent means "${SESSION_KIND}".`,
+      );
+    }
+  }
+  // A CHAT TURN NAMES WHERE IT RUNS AND WHICH ROOM IT IS, and neither is
+  // optional. It mints no worktree (brief 25, difference 2), so `cwd` is the
+  // only directory it could possibly run in and a fallback to the linked
+  // checkout would put a chat agent in his working tree. And its lock is
+  // per-ROOM rather than per-prompt (difference 4), so without `roomId` there
+  // is nothing to lock and two messages typed quickly become two live turns
+  // in one conversation.
+  //
+  // That the directory EXISTS is checked by the runner rather than here: this
+  // function is pure and synchronous by design, and every caller of it is a
+  // caller that has not touched the disk yet.
+  if (isChatTurn(request)) {
+    if (typeof request.cwd !== "string" || request.cwd.trim() === "") {
+      found.note(
+        "A chat-turn request must name cwd: the directory the conversation lives in. A chat turn never mints a worktree, and Claude Code keeps conversations per working directory, so the directory IS which conversation this is.",
+      );
+    }
+    if (typeof request.roomId !== "string" || request.roomId.trim() === "") {
+      found.note(
+        "A chat-turn request must name roomId: which DM this turn belongs to. It is what the per-room lock locks, and one live turn per room is the only thing stopping two messages typed a second apart from running at once.",
+      );
+    }
+  }
+  // MAY THE RUNNER CUT THE CHAT WORKTREE? A boolean, and only `true` means
+  // yes - a string "true" buys nothing, the same rule `approved` follows. It
+  // is validated for every kind rather than only a chat turn so that the
+  // field cannot mean one thing on one file and something else on another:
+  // nothing but a chat turn reads it, and a session request carrying it is a
+  // request that has misunderstood something.
+  if (request.mintIfMissing !== undefined && typeof request.mintIfMissing !== "boolean") {
+    found.note(
+      "mintIfMissing, when present, is a boolean: true asks the runner to create a chat turn's cwd as this folder's chat worktree if it is not there. Anything else is refused rather than read as true.",
+    );
+  }
+  // THE BOARD'S SUBFOLDER (2026-09-30): a chat turn in the Glytch folder runs
+  // in one folder per board inside its chat worktree. One name, never a path.
+  if (request.boardFolder !== undefined && (!isChatTurn(request) || !isBoardFolderName(request.boardFolder))) {
+    found.note(
+      "boardFolder, when present, is on a chat turn and is one folder name: at most 80 characters, no slashes, no leading dot, none of < > : \" | ? *.",
+    );
+  }
+  // WHICH IDEAS THIS CAME FROM. Optional, because a hand-written request
+  // from the CLI has no ideas behind it and refusing one would make the
+  // terminal path unusable. Validated when present, because a malformed id
+  // reaching the board is a proposal pointing at nothing.
+  if (request.nodeIds !== undefined) {
+    if (!Array.isArray(request.nodeIds) || request.nodeIds.some((n) => typeof n !== "string" || n.trim() === "")) {
+      found.note(
+        "nodeIds, when present, records which board ideas the run came from and must be an array of non-empty strings. It is how a session comes home to the idea that asked for it.",
+      );
+    }
+  }
+  // WHICH ENGINE. Optional - absent means the runner's default, so every
+  // request filed before engines were plural still runs. Validated as a
+  // string when present; an unknown NAME is not refused here, because the
+  // runner falls back to the default and says which ran rather than dying
+  // while holding a claim on a request nobody will retry.
+  if (request.agent !== undefined && (typeof request.agent !== "string" || request.agent.trim() === "")) {
+    found.note(
+      "agent, when present, names which engine runs this session and must be a non-empty string.",
+    );
+  }
+  // WHICH MODEL, and HOW HARD TO THINK. Both optional, both free-form: the
+  // vocabulary is the engine's, not ours - Claude Code takes aliases or full
+  // names, opencode takes provider/model and its own variant names - and a
+  // list here would go stale the week either of them adds one.
+  for (const field of ["model", "effort"]) {
+    if (request[field] !== undefined && (typeof request[field] !== "string" || request[field].trim() === "")) {
+      found.note(
+        `${field}, when present, must be a non-empty string. Its vocabulary belongs to the engine that runs the session, so it is passed through rather than checked against a list.`,
+      );
+    }
+  }
+  if (request.useWorktree !== undefined && typeof request.useWorktree !== "boolean") {
+    found.note(
+      "useWorktree, when present, must be a boolean. Set to false to run in the linked checkout instead of an isolated worktree.",
+    );
+  }
+  if (request.webSearch !== undefined && typeof request.webSearch !== "boolean") {
+    found.note(
+      "webSearch, when present, must be a boolean. True lets a run on this computer search and read the web without asking first.",
+    );
+  }
+  if (request.computerApps !== undefined && typeof request.computerApps !== "boolean") {
+    found.note(
+      "computerApps, when present, must be a boolean. True lets this run use the apps the person set up in Claude Code or Codex.",
+    );
+  }
+  // PERSISTENT SESSIONS: session id fields are UUIDs, worktreePath is an
+  // absolute path. All are optional. Validated as strings when present.
+  for (const field of ["sessionId", "resumeSessionId"]) {
+    if (request[field] !== undefined && (typeof request[field] !== "string" || request[field].trim() === "")) {
+      found.note(
+        `${field}, when present, must be a non-empty string (a UUID). It controls whether the session resumes or starts fresh.`,
+      );
+    }
+  }
+  if (request.worktreePath !== undefined && (typeof request.worktreePath !== "string" || request.worktreePath.trim() === "")) {
+    found.note(
+      "worktreePath, when present, must be a non-empty string (an absolute path to a git worktree to reuse for session resume).",
+    );
+  }
+  if (request.maxMs !== undefined) {
+    if (typeof request.maxMs !== "number" || !Number.isFinite(request.maxMs) || request.maxMs <= 0) {
+      found.note(`maxMs, when present, is this session's wall clock in milliseconds and must be a positive number, at most ${MAX_WALL_MS}.`);
+    } else if (request.maxMs > MAX_WALL_MS) {
+      found.note(
+        `maxMs is ${request.maxMs}, and the longest a session runs is ${MAX_WALL_MS} (${MAX_WALL_MS / 3_600_000}h). A session that hangs bills until it is killed, so no request runs longer.`,
+      );
+    }
+  }
+  return found.list;
+}
+
+/** The wall clock this request actually gets, held to MAX_WALL_MS. */
+export const wallClockFor = (request) =>
+  typeof request?.maxMs === "number" && request.maxMs > 0
+    ? Math.min(request.maxMs, MAX_WALL_MS)
+    : DEFAULT_WALL_MS;
+
+/** The title this request's idea gets: its own, or the prompt's first line. */
+export function titleFor(request) {
+  if (typeof request?.title === "string" && request.title.trim() !== "") return request.title.trim();
+  const first = String(request?.prompt ?? "").replace(/\s+/g, " ").trim();
+  return first.length > 60 ? `${first.slice(0, 57)}...` : first || "Coding session";
+}

package/lib/sweep.mjs

@@ -0,0 +1,161 @@
+// WHAT THE FILE TRANSPORT LEAVES BEHIND, and nobody needs any more.
+//
+// Ruling 5 (2026-09-06): files stay the transport, with two duties added to
+// the daemon. This is the first - a sweep on start and once a day. The second
+// is lib/sync.mjs.
+//
+// THE NEVER-TOUCH LIST IS THE POINT OF THIS FILE, so it is spelled first:
+//
+//   - the mark file (.glytch/inbox/spawn/.runner.json) - the app reads it
+//     every tick to decide whether a runner is watching. It is a dotfile and
+//     no id-prefixed rule can reach it, and this module never lists it;
+//   - the mirror (.glytch/canvas/) - written by the browser, read by every
+//     session. Nothing here goes near that directory;
+//   - .glytch/inbox/ops/ and the top-level inbox files - ops the app has not
+//     ingested yet. A swept op is a proposal that never reached the user, so
+//     the sweep does not have a rule for them at all: it only ever reads
+//     .glytch/inbox/spawn/;
+//   - an UNFINISHED request. "Finished" here means a terminal receipt exists
+//     (<id>.result.txt, the one spawn.mjs writes exactly once). A request
+//     that is filed and waiting, claimed and running, or claimed by a runner
+//     that died, has no receipt and is never touched however old it is - a
+//     leaked claim is released by a person (`release`), by the ruling, and a
+//     sweep that guessed would be the reaper that ruling refused;
+//   - EVERY WORKTREE, and CHAT WORKTREES BY NAME (added 2026-09-07, brief 25,
+//     ruling 1: "one long-lived chat worktree per agent per folder, made
+//     once and kept"). This module has never removed a directory under
+//     `.claude/worktrees/` - it reads `.glytch/inbox/spawn/` and nothing else,
+//     so a 14-day-old chat turn loses its request FILES and the agent keeps
+//     the tree its conversation lives in. That is the correct behaviour and
+//     is now pinned by a test (`bridge/test/chatturn.test.mjs`, "the sweep
+//     takes a chat turn's old files and leaves its worktree alone"), because
+//     it is currently true by omission: a stale-worktree rule added here
+//     later must skip `<root>/.claude/worktrees/chat-*` (isChatWorktreePath,
+//     lib/worktree.mjs). A chat tree is removed when the AGENT is deleted,
+//     and by nothing else.
+//
+// THE AGE IS MEASURED FROM THE RECEIPT, not from the request: a request filed
+// in June and finished yesterday is a session whose log the app may still be
+// showing. 14 days by default, which is well past the point where a session
+// frame is history rather than work in progress.
+//
+// THE DETACHED DEV SERVERS ARE NOT THIS FILE'S JOB ANY MORE. From 2026-09-06
+// to brief 30 it read a `<id>.server` mirror beside the receipt and stopped
+// the process it named; brief 30 moved that record onto the run row and the
+// mirror stopped being written, which left this loop reading nothing for a
+// week. lib/serverSweep.mjs stops them from rows, off the runner's own beat.
+
+import { access, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { LOG_KEEP, staleRotations } from "./logs.mjs";
+import { pruneMissing } from "./registry.mjs";
+import { RECEIPT_SUFFIX, SPAWN_DIR, listRequests } from "./spawn.mjs";
+
+export const SWEEP_AGE_MS = 14 * 86_400_000;
+
+const mtimeOf = async (path) => {
+  try {
+    return (await stat(path)).mtimeMs;
+  } catch {
+    return null;
+  }
+};
+
+const exists = async (path) => {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** Sweep one folder's spawn channel. Returns {removed, kept, skipped} - names,
+ * not paths, so a log line is readable. Never throws: a folder that vanished
+ * mid-sweep is one of the states this whole feature exists to survive.
+ *
+ * A stopped dev server is reported through `log` and not in the return value:
+ * the shape of this result is asserted whole by bridge/test/sweep.test.mjs
+ * ("a folder with no spawn channel at all sweeps to nothing, quietly"), and a
+ * new field would have meant editing a test to add a feature.
+ *
+ * `stopServer` is injected so the decision to stop can be tested without a
+ * process table under it; the default is the real one. */
+export async function sweepFolder(root, { now = Date.now(), ageMs = SWEEP_AGE_MS, log = () => {} } = {}) {
+  const dir = join(root, SPAWN_DIR);
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    return { removed: [], kept: [], skipped: [] };
+  }
+  const removed = [];
+  const kept = [];
+  const skipped = [];
+  const sweeping = new Map();
+  for (const id of await listRequests(root)) {
+    const finishedAt = await mtimeOf(join(dir, `${id}${RECEIPT_SUFFIX}`));
+    if (finishedAt === null) {
+      // No receipt: not finished. Never touched, whatever its age.
+      skipped.push(id);
+      continue;
+    }
+    if (now - finishedAt <= ageMs) {
+      kept.push(id);
+      continue;
+    }
+    sweeping.set(id, finishedAt);
+  }
+
+  for (const [id, finishedAt] of sweeping) {
+    // Everything this request owns, and nothing else. Request ids carry no
+    // dot, so `${id}.` cannot reach another request's files, and the leading
+    // dot of `.runner.json` puts the mark file out of reach by construction.
+    for (const name of names.filter((n) => n.startsWith(`${id}.`))) {
+      try {
+        await rm(join(dir, name), { force: true });
+        removed.push(name);
+      } catch {
+        /* a file someone else is holding is left alone */
+      }
+    }
+    log(`swept ${id}: finished ${Math.round((now - finishedAt) / 86_400_000)} days ago`);
+  }
+  return { removed, kept, skipped };
+}
+
+/** The whole sweep: every registered folder, the rotated logs past the keep
+ * count, and the registry entries whose folder is gone.
+ *
+ * A dropped registry entry gets ONE LOG LINE and never an exit - a project
+ * folder that was moved or deleted is an ordinary thing for a machine-wide
+ * daemon to meet, and taking the daemon down over it would stop every other
+ * folder too. */
+export async function sweepAll({
+  env = process.env,
+  now = Date.now(),
+  ageMs = SWEEP_AGE_MS,
+  keep = LOG_KEEP,
+  log = () => {},
+} = {}) {
+  const { kept: folders, dropped } = await pruneMissing(env);
+  for (const gone of dropped) log(`forgetting ${gone}: the folder no longer exists`);
+
+  const swept = [];
+  for (const folder of folders) {
+    const result = await sweepFolder(folder, { now, ageMs, log: (line) => log(`[${folder}] ${line}`) });
+    if (result.removed.length > 0) swept.push({ folder, removed: result.removed.length });
+  }
+
+  const logs = [];
+  for (const path of await staleRotations({ keep, env })) {
+    try {
+      await rm(path, { force: true });
+      logs.push(path);
+      log(`removed rotated log past keep ${keep}: ${path}`);
+    } catch {
+      /* leave it */
+    }
+  }
+  return { folders, dropped, swept, logs };
+}