@coreplane/switchboard 1.202.0 → 1.203.0

package/bin/switchboard.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// The `switchboard` bin: this file hands the process to dist/cli.js, the bundle
+// the build writes (build.mts; docs/reference/specs/packaging.md item 1). A
+// committed entry rather than the bundle itself, because npm links a bin only
+// when its target exists at install time, and the gitignored dist/ does not
+// until the build runs: with dist/cli.js as the bin, `npx <the package>` inside
+// the checkout — where npx prefers the workspace over the registry — found no
+// link and died with `sh: switchboard: command not found`. The published package
+// always carries the bundle, so there this is one extra module load; a checkout
+// that has not built the package is told what to run.
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const bundle = new URL("../dist/cli.js", import.meta.url);
+
+if (!existsSync(bundle)) {
+  console.error(
+    `switchboard: ${fileURLToPath(bundle)} is missing — the package is not built. Inside the checkout, npx runs this workspace, not the published package: run \`npm run build -w packages/switchboard\` first, or use the checkout's CLI, \`npm run cli -- <group> <verb> …\`.`,
+  );
+  process.exit(1);
+}
+
+// From here the bundle is the script: its entry claim (src/invokedAsScript.ts)
+// and its usage spelling (`programName`, src/cli.ts) read argv[1].
+process.argv[1] = fileURLToPath(bundle);
+await import(bundle.href);

package/dist/assets/config/config.example.yaml

@@ -272,6 +272,16 @@ workspaceDir: ./workspaces
 #         some-other-bucket: uploads
 #       anthropicWorkspaceId: wrkspc_...          # this app's Anthropic workspace
 
+# Delivery indicators: GET /delivery and `delivery report` (docs/reference/specs/delivery.md).
+# Optional. Needs a GitHub credential (the App triple or GH_TOKEN); read-only.
+# delivery:
+#   repos: [acme/api, acme/web]          # the repositories the page serves; the first is its default
+#                                        #   (`delivery report --repo owner/name` needs no entry here)
+#   reviewers: []                        # logins whose reviews count as the review agent's verdicts,
+#                                        #   beside this installation's own App identity
+#   agentLogins: []                      # logins that are agents beyond the `[bot]` suffix
+#   agentCoauthors: [Claude]             # `Co-Authored-By:` names that mark a commit as an agent's
+
 # Dashboard authentication (docs/reference/specs/access-gate.md). Everything the dashboard
 # serves — /runs*, /residents*, /costs*, /mcp/connect/*, and every /api/* command
 # — sits behind ONE identity gate; `auth` picks which credential it checks:

package/dist/assets/deploy/cloudflare-resident/preflight.mjs

@@ -41,8 +41,8 @@ const SETTLED_STATES = new Set(["warm", "degraded", "down"]);
  *  is `provision-failed`, `down`, and only a rebuild recovers it. */
 const PROVISIONING_STATES = new Set(["onboarding"]);
 /** The engine is executing and an isolate swap merely INTERRUPTS it: a refresh
- *  cycle re-arms in 45 s and resumes from its disk checkpoints (resident-repos
- *  items 44 and 48); a restore is retried by the next hydrate, which first
+ *  step is retried by its Workflow instance and resumes from its disk
+ *  checkpoints (resident-repos items 44 and 48); a restore is retried by the next hydrate, which first
  *  unmounts and removes whatever the interrupted one left (item 61). These
  *  used to refuse like `onboarding`, and a release deploy once spent its whole
  *  budget behind a resident stuck in `restoring` — a state an isolate swap
@@ -162,7 +162,7 @@ export function decide(fetched, { force = false } = {}) {
   // Interruptible cycles never refuse; they are named so the log says what the
   // swap interrupts and why that is fine.
   const warningText = interrupting.length
-    ? ` — WARNING: mid-cycle: ${interrupting.map((m) => `${m.resource} (${m.state})`).join(", ")} — the isolate swap interrupts it; a refresh re-arms in 45 s from its checkpoints, a restore is retried by the next hydrate (resident-repos items 44/61)`
+    ? ` — WARNING: mid-cycle: ${interrupting.map((m) => `${m.resource} (${m.state})`).join(", ")} — the isolate swap interrupts it; the refresh instance retries the step from its checkpoints, a restore is retried by the next hydrate (resident-repos items 44/61)`
     : "";
 
   if (problems.length === 0) {

package/dist/assets/deploy/cloudflare-resident/refresh.ts

@@ -1,10 +1,11 @@
 // The refresh cycle as a Workflow instance (docs/reference/specs/resident-repos.md
 // item 7): the `ResidentRefresh` entrypoint the Workflows binding names, the
-// watchdog cron's instance-creation duty (`createRefreshInstance`) and the
-// existence probe it confirms a duplicate-id refusal with. The steps' own work
-// stays in worker.ts as the Durable Object's `refreshInstance*` methods: this
-// module only sequences them through the DO stub. The entry re-exports the
-// class (the binding resolves `class_name` against the entry module), and
+// watchdog cron's instance-creation duty (`createRefreshInstance`), the admin
+// `refresh-now` op's on-demand creation (`createRefreshInstanceNow`) and the
+// existence probe a duplicate-id refusal is confirmed with. The steps' own
+// work stays in worker.ts as the Durable Object's `refreshInstance*` methods:
+// this module only sequences them through the DO stub. The entry re-exports
+// the class (the binding resolves `class_name` against the entry module), and
 // nothing here imports the entry at runtime — the shared pieces come from
 // shared.ts, the entry's types `type`-only.
 import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
@@ -12,6 +13,7 @@ import { systemClock } from "../../src/core/trace/clock.js";
 import { startAdoptedRoot } from "../../src/core/trace/workerTrace.js";
 import {
   REFRESH_STEP_RETRIES,
+  refreshCycleBlocked,
   refreshInstanceId,
   shouldCreateRefreshInstance,
   stepTimeoutMs,
@@ -21,6 +23,7 @@ import { RESTORE_MAX_MS, type RefreshPlan } from "../../src/execution/residentRe
 import { residentText } from "../../src/execution/residentText.js";
 import { graftResidentSteps } from "../../src/execution/residentTrace.js";
 import {
+  DEFAULT_EXEC_TIMEOUT_MS,
   DEPS_STEP_OVERHEAD_MS,
   errMsg,
   GIT_NETWORK_TIMEOUT_MS,
@@ -30,6 +33,7 @@ import {
   REFRESH_INSTALL_TIMEOUT_MS,
   REFRESH_INTERVAL_S,
   residentStub,
+  THREAD_POOL_SIZE,
   tracer,
   traceSinks,
 } from "./shared";
@@ -41,7 +45,7 @@ export interface RefreshInstanceParams {
   resource: string;
 }
 
-/** What the cron did about one resident's refresh instance this pass. */
+/** What a creator did about one resident's refresh instance. */
 export interface RefreshInstanceAction {
   id: string;
   action: "created" | "duplicate" | "skipped" | "failed";
@@ -54,7 +58,13 @@ export interface RefreshInstanceAction {
 const REFRESH_FETCH_STEP_BUDGET_MS = RESTORE_MAX_MS + GIT_NETWORK_TIMEOUT_MS; // a wake's restore, then the fetch
 const REFRESH_INSTALL_STEP_BUDGET_MS = REFRESH_INSTALL_TIMEOUT_MS + DEPS_STEP_OVERHEAD_MS; // the install's own lease
 const REFRESH_BUILD_STEP_BUDGET_MS = GIT_NETWORK_TIMEOUT_MS + REFRESH_BUILD_TIMEOUT_MS; // the build's mutex lease
-const REFRESH_SNAPSHOT_STEP_BUDGET_MS = R2_TRANSFER_TIMEOUT_MS + GIT_NETWORK_TIMEOUT_MS; // the archives, then the reclaim pass and the disk sample
+const REFRESH_SNAPSHOT_STEP_BUDGET_MS = R2_TRANSFER_TIMEOUT_MS + GIT_NETWORK_TIMEOUT_MS; // the archives, then the reclaim pass
+/** The sweep: one cleanliness check per binding idle past an hour (at most the
+ *  pool's worth, one exec budget each), then the removals under the mirror lock. */
+const REFRESH_SWEEP_STEP_BUDGET_MS = THREAD_POOL_SIZE * DEFAULT_EXEC_TIMEOUT_MS + GIT_NETWORK_TIMEOUT_MS;
+/** The measurement: `df`, the `du` over the parts and the store's listing (one
+ *  network-class budget each), then the store's removals. */
+const REFRESH_MEASURE_STEP_BUDGET_MS = 2 * GIT_NETWORK_TIMEOUT_MS + DEFAULT_EXEC_TIMEOUT_MS;
 
 /** Whether the engine knows an instance by this id, in any status. A missing
  *  id rejects on `get` or on `status`; either way the answer is false. */
@@ -67,51 +77,85 @@ async function refreshInstanceExists(env: Env, id: string): Promise<boolean> {
   }
 }
 
-/** The cron's instance-creation duty for one resident (item 7). Only a
- *  `workflow` row gets an instance, at most one per ten-minute bucket, never
- *  while a cycle is live (`shouldCreateRefreshInstance`); the id is
+/** The deterministic id for this resident's current bucket. */
+function bucketInstanceId(resource: string, nowMs: number): string {
+  const slug = resource.slice("repo:".length);
+  const slash = slug.indexOf("/");
+  return refreshInstanceId(slug.slice(0, slash), slug.slice(slash + 1), nowMs);
+}
+
+/** Create the instance `id` for `resource` and record the outcome on the row.
+ *  The engine refuses an id that names an instance still inside its retention,
+ *  and the refusal carries no code — so the id is asked, not the wording: an
+ *  instance that answers for it exists, and the refusal was the duplicate it
+ *  looks like. Any other failure stays a failure. */
+async function createInstance(
+  env: Env,
+  stub: ReturnType<typeof residentStub>,
+  resource: string,
+  id: string,
+  nowMs: number,
+  why: string,
+): Promise<RefreshInstanceAction> {
+  try {
+    await env.RESIDENT_REFRESH.create({ id, params: { resource } });
+  } catch (err) {
+    const message = errMsg(err);
+    if (await refreshInstanceExists(env, id)) {
+      await stub.recordRefreshSkipped(id, nowMs, "duplicate");
+      return { id, action: "duplicate", why: "duplicate" };
+    }
+    console.error(`resident-watchdog: creating refresh instance ${id} failed — ${message}`);
+    return { id, action: "failed", why: residentText(message) };
+  }
+  await stub.recordRefreshInstance(id, nowMs);
+  console.log(`resident-watchdog: created refresh instance ${id} (${why})`);
+  return { id, action: "created", why };
+}
+
+/** The cron's instance-creation duty for one resident (item 7): at most one
+ *  instance per ten-minute bucket, never while a cycle is live, only once the
+ *  cadence has elapsed (`shouldCreateRefreshInstance`); the id is
  *  deterministic per resident and bucket, so a second firing in one bucket
  *  meets the engine's duplicate-id refusal, which is the expected no-op. A
- *  skipped live cycle and a duplicate are recorded on the row for `/status`.
- *  An `alarm` resident answers null: nothing here touches it. */
+ *  skipped live cycle and a duplicate are recorded on the row for `/status`. */
 export async function createRefreshInstance(
   env: Env,
   stub: ReturnType<typeof residentStub>,
   resource: string,
   row: RefreshRow,
-): Promise<RefreshInstanceAction | null> {
-  if (row.lifecycle !== "workflow") return null;
+): Promise<RefreshInstanceAction> {
   const now = systemClock();
   const decision = shouldCreateRefreshInstance(row, now, {
     intervalS: REFRESH_INTERVAL_S,
     idleIntervalS: IDLE_REFRESH_INTERVAL_S,
   });
-  const slug = resource.slice("repo:".length);
-  const slash = slug.indexOf("/");
-  const id = refreshInstanceId(slug.slice(0, slash), slug.slice(slash + 1), now);
+  const id = bucketInstanceId(resource, now);
   if (!decision.create) {
     if (decision.why === "mid-cycle" || decision.why === "running")
       await stub.recordRefreshSkipped(id, now, decision.why);
     return { id, action: "skipped", why: decision.why };
   }
-  try {
-    await env.RESIDENT_REFRESH.create({ id, params: { resource } });
-  } catch (err) {
-    const message = errMsg(err);
-    // The engine refuses an id that names an instance still inside its
-    // retention, and the refusal carries no code — so the id is asked, not
-    // the wording: an instance that answers for it exists, and the refusal
-    // was the duplicate it looks like. Any other failure stays a failure.
-    if (await refreshInstanceExists(env, id)) {
-      await stub.recordRefreshSkipped(id, now, "duplicate");
-      return { id, action: "duplicate", why: "duplicate" };
-    }
-    console.error(`resident-watchdog: creating refresh instance ${id} failed — ${message}`);
-    return { id, action: "failed", why: residentText(message) };
-  }
-  await stub.recordRefreshInstance(id, now);
-  console.log(`resident-watchdog: created refresh instance ${id}`);
-  return { id, action: "created", why: decision.why };
+  return createInstance(env, stub, resource, id, now, decision.why);
+}
+
+/** The admin `refresh-now` op (item 13): this bucket's instance, created now,
+ *  due or not — the cycle the cron would create at its next firing, started
+ *  on demand. Never beside a live cycle (`refreshCycleBlocked`: a running
+ *  instance, a young `refreshing` marker, a resident that is not serving —
+ *  answered `skipped` with the why), and under the bucket's deterministic id,
+ *  so a bucket the cron already served answers `duplicate` naming that
+ *  instance: the next bucket is at most ten minutes away. */
+export async function createRefreshInstanceNow(
+  env: Env,
+  stub: ReturnType<typeof residentStub>,
+  resource: string,
+): Promise<RefreshInstanceAction> {
+  const now = systemClock();
+  const id = bucketInstanceId(resource, now);
+  const blocked = refreshCycleBlocked(await stub.refreshRow(), now);
+  if (blocked) return { id, action: "skipped", why: blocked };
+  return createInstance(env, stub, resource, id, now, "refresh-now");
 }
 
 /** What an instance answers when it ends: small facts for the engine's record. */
@@ -119,33 +163,42 @@ interface RefreshInstanceSummary {
   instance: string;
   /** `ok`, or the word a gate or a failure ended the cycle with. */
   outcome: string;
+  /** The step the cycle's verdict came from. */
   step: "fetch" | "install" | "build" | "snapshot";
   action?: RefreshPlan["action"];
   sha?: string;
+  /** The housekeeping steps' answers, when they ran. */
+  swept?: { evicted: number; kept: number } | null;
+  measured?: boolean;
 }
 
 /** One refresh cycle as one short Workflow instance: `fetch`, `install` (only
  *  when the plan moved the lockfile key), `build` (only when the branch
- *  moved), `snapshot` — each a `step.do` calling the resident's own step
- *  method through the DO stub, under the retry policy `REFRESH_STEP_RETRIES`
- *  (six attempts, thirty seconds apart, doubling: about 15.5 minutes, past
- *  the 3 to 10 minutes a resident Worker rollover takes to settle) and a
- *  timeout equal to the method's own budget (never above the engine's 30
- *  minutes). Inputs to a step are the event's `resource`, the instance id and
- *  previous steps' returns — refs, shas, a key, a path — never a payload and
- *  never a credential. A step killed from outside (the container replaced
- *  under it) throws and the engine retries it into the same idempotent
- *  method; a gate that ends the cycle (idle, a container restart) or a
- *  failure of the repository's own (recorded as `degraded`, the last snapshot
- *  still serving) ends the instance with that word, and the next cron firing
- *  creates the next one from the row's state. The instance runs one cycle
- *  and returns: it is created by the watchdog cron per resident and
- *  ten-minute bucket (`createRefreshInstance`), never a loop.
+ *  moved), `snapshot`, then the housekeeping `sweep` (the worktree
+ *  inactivity eviction, item 23) and `measure` (the disk sample, item 55) —
+ *  each a `step.do` calling the resident's own step method through the DO
+ *  stub, under the retry policy `REFRESH_STEP_RETRIES` (six attempts, thirty
+ *  seconds apart, doubling: about 15.5 minutes, past the 3 to 10 minutes a
+ *  resident Worker rollover takes to settle) and a timeout equal to the
+ *  method's own budget (never above the engine's 30 minutes). Inputs to a
+ *  step are the event's `resource`, the instance id and previous steps'
+ *  returns — refs, shas, a key, a path — never a payload and never a
+ *  credential. A step killed from outside (the container replaced under it)
+ *  throws and the engine retries it into the same idempotent method; so does
+ *  a gate that stopped the container on purpose (a stale image, a disk-full
+ *  recycle) — the retry finds the container back and continues the cycle. A
+ *  gate that ends the cycle (idle, an offboard) or a failure of the
+ *  repository's own (recorded as `degraded`, the last snapshot still serving)
+ *  ends the cycle with that word; the housekeeping steps still run for every
+ *  verdict but an offboard (nothing is left to keep), and neither wakes a
+ *  slept container. The instance runs one cycle and returns: it is created by
+ *  the watchdog cron per resident and ten-minute bucket
+ *  (`createRefreshInstance`) or by the admin `refresh-now` op, never a loop;
+ *  the next cron firing creates the next one from the row's state.
  *
  *  The run is the cycle's root span, `resident.refresh` carrying the instance
  *  id (docs/reference/specs/tracing.md item 25), with every command a step ran
- *  grafted under it as a `resident.<step>` child — the same shape the alarm's
- *  root has. */
+ *  grafted under it as a `resident.<step>` child. */
 export class ResidentRefresh extends WorkflowEntrypoint<Env, RefreshInstanceParams> {
   async run(
     event: Readonly<WorkflowEvent<RefreshInstanceParams>>,
@@ -167,7 +220,7 @@ export class ResidentRefresh extends WorkflowEntrypoint<Env, RefreshInstancePara
         clipAt: systemClock(),
       });
     const retries = REFRESH_STEP_RETRIES;
-    /** The word a step that did not finish ends the instance with, and its outcome for the root. */
+    /** The word a step that did not finish ends the cycle with. */
     const ended = (
       at: RefreshInstanceSummary["step"],
       answer: { status: "stopped"; why: string } | { status: "failed"; reason: string },
@@ -178,53 +231,86 @@ export class ResidentRefresh extends WorkflowEntrypoint<Env, RefreshInstancePara
     });
     let summary: RefreshInstanceSummary | undefined;
     try {
+      let cycle: RefreshInstanceSummary | undefined;
       const fetched = await step.do("fetch", { retries, timeout: stepTimeoutMs(REFRESH_FETCH_STEP_BUDGET_MS) }, () =>
         stub.refreshInstanceFetch({ resource, instance }),
       );
       graft(fetched);
-      if (fetched.status !== "done") return (summary = ended("fetch", fetched));
-      let depsEntry: string | null = null;
-      if (fetched.install) {
-        const installed = await step.do(
-          "install",
-          { retries, timeout: stepTimeoutMs(REFRESH_INSTALL_STEP_BUDGET_MS) },
-          () => stub.refreshInstanceInstall({ resource, instance, sha: fetched.sha, lockfileKey: fetched.lockfileKey }),
-        );
-        graft(installed);
-        if (installed.status !== "done") return (summary = ended("install", installed));
-        depsEntry = installed.entry;
+      if (fetched.status !== "done") cycle = ended("fetch", fetched);
+      else {
+        let depsEntry: string | null = null;
+        if (fetched.install) {
+          const installed = await step.do(
+            "install",
+            { retries, timeout: stepTimeoutMs(REFRESH_INSTALL_STEP_BUDGET_MS) },
+            () =>
+              stub.refreshInstanceInstall({ resource, instance, sha: fetched.sha, lockfileKey: fetched.lockfileKey }),
+          );
+          graft(installed);
+          if (installed.status !== "done") cycle = ended("install", installed);
+          else depsEntry = installed.entry;
+        }
+        if (cycle === undefined && fetched.action !== "unchanged") {
+          const built = await step.do("build", { retries, timeout: stepTimeoutMs(REFRESH_BUILD_STEP_BUDGET_MS) }, () =>
+            stub.refreshInstanceBuild({
+              resource,
+              instance,
+              sha: fetched.sha,
+              factsSha: fetched.factsSha,
+              lockfileKey: fetched.lockfileKey,
+              depsEntry,
+            }),
+          );
+          graft(built);
+          if (built.status !== "done") cycle = ended("build", built);
+        }
+        if (cycle === undefined) {
+          const snapped = await step.do(
+            "snapshot",
+            { retries, timeout: stepTimeoutMs(REFRESH_SNAPSHOT_STEP_BUDGET_MS) },
+            () =>
+              stub.refreshInstanceSnapshot({
+                resource,
+                instance,
+                ref: fetched.ref,
+                sha: fetched.sha,
+                lockfileKey: fetched.lockfileKey,
+                action: fetched.action,
+                mintError: fetched.mintError,
+              }),
+          );
+          graft(snapped);
+          cycle =
+            snapped.status !== "done"
+              ? ended("snapshot", snapped)
+              : { instance, outcome: "ok", step: "snapshot", action: fetched.action, sha: fetched.sha };
+        }
       }
-      if (fetched.action !== "unchanged") {
-        const built = await step.do("build", { retries, timeout: stepTimeoutMs(REFRESH_BUILD_STEP_BUDGET_MS) }, () =>
-          stub.refreshInstanceBuild({
-            resource,
-            instance,
-            sha: fetched.sha,
-            factsSha: fetched.factsSha,
-            lockfileKey: fetched.lockfileKey,
-            depsEntry,
-          }),
+      // Housekeeping rides on every instance whatever the cycle's verdict — a
+      // parked resident still releases its idle bindings and re-measures, and
+      // neither step wakes a slept container — except an offboarded one:
+      // nothing is left to keep.
+      if (cycle.outcome !== "offboarded") {
+        const swept = await step.do("sweep", { retries, timeout: stepTimeoutMs(REFRESH_SWEEP_STEP_BUDGET_MS) }, () =>
+          stub.refreshInstanceSweep({ resource, instance }),
         );
-        graft(built);
-        if (built.status !== "done") return (summary = ended("build", built));
+        graft(swept);
+        const measured = await step.do(
+          "measure",
+          { retries, timeout: stepTimeoutMs(REFRESH_MEASURE_STEP_BUDGET_MS) },
+          () => stub.refreshInstanceMeasure({ instance }),
+        );
+        graft(measured);
+        cycle = {
+          ...cycle,
+          swept:
+            swept.status === "done" && swept.result
+              ? { evicted: swept.result.evicted.length, kept: swept.result.kept }
+              : null,
+          measured: measured.status === "done" && measured.result !== null && measured.result.measured,
+        };
       }
-      const snapped = await step.do(
-        "snapshot",
-        { retries, timeout: stepTimeoutMs(REFRESH_SNAPSHOT_STEP_BUDGET_MS) },
-        () =>
-          stub.refreshInstanceSnapshot({
-            resource,
-            instance,
-            ref: fetched.ref,
-            sha: fetched.sha,
-            lockfileKey: fetched.lockfileKey,
-            action: fetched.action,
-            mintError: fetched.mintError,
-          }),
-      );
-      graft(snapped);
-      if (snapped.status !== "done") return (summary = ended("snapshot", snapped));
-      return (summary = { instance, outcome: "ok", step: "snapshot", action: fetched.action, sha: fetched.sha });
+      return (summary = cycle);
     } catch (err) {
       // A step out of retries: the engine records the failed instance by id;
       // the row keeps its last state and the next cron firing starts the next cycle.

package/dist/assets/deploy/cloudflare-resident/shared.ts

@@ -19,20 +19,25 @@ import type { Env } from "./worker";
  *  resident is re-warmed before the platform can sleep it. Bump together. */
 export const SLEEP_AFTER = "20m";
 
-/** Refresh alarm cadence (seconds). Each resident DO self-reschedules this
- *  alarm (per-resident alarms own freshness; the sparse cron is only the
- *  watchdog); it doubles as the keep-warm heartbeat, so it must stay below
- *  SLEEP_AFTER. Matches the watchdog cron so a killed chain is re-armed
- *  within one refresh interval. */
+/** The refresh cadence (seconds): one instance per resident per ten-minute
+ *  bucket, created by the watchdog cron, so the cron's own period is the
+ *  cadence. The cycle doubles as the keep-warm heartbeat (its steps call into
+ *  the container), so it must stay below SLEEP_AFTER. */
 export const REFRESH_INTERVAL_S = 600;
 
-/** How far out an idle resident's cycle is parked (seconds): the alarm's idle
- *  re-arm (`IDLE_AFTER_S` in worker.ts decides idleness) and the cron's idle
- *  cadence, in whole ten-minute buckets since the last instance. */
+/** How far out an idle resident's next cycle is (seconds): the cron's idle
+ *  cadence (`IDLE_AFTER_S` in worker.ts decides idleness), in whole
+ *  ten-minute buckets since the last instance. */
 export const IDLE_REFRESH_INTERVAL_S = 6 * 60 * 60;
 
-/** Exec budgets. The DO alarm handler has a ~15-minute platform wall clock;
- *  every schedule callback's step budgets are chosen to fit under it. */
+/** The thread user pool the image carries (`worker2`..`worker17`): one OS
+ *  user per attached thread, and the bound on how many bindings one sweep
+ *  step can have to check. */
+export const THREAD_POOL_SIZE = 16;
+
+/** Exec budgets. Each is a refresh step's own budget too (refresh.ts), so a
+ *  step timeout and the command timeout it bounds agree; every one is under
+ *  the engine's 30-minute step ceiling. */
 export const DEFAULT_EXEC_TIMEOUT_MS = 60_000;
 export const GIT_NETWORK_TIMEOUT_MS = 5 * 60_000;
 export const REFRESH_BUILD_TIMEOUT_MS = 5 * 60_000;