@codeyam-editor/codeyam-editor 0.1.0-staging.01efa1a

package/npm/fleet-env.js

@@ -0,0 +1,125 @@
+'use strict';
+// Pure helpers for the fleet dashboard's per-VM environment-variable feature
+// (scripts/operator/fleet-dashboard/server.js requires this). Parsing,
+// validation, and formatting only — no I/O, no secret logging — so it stays
+// unit-testable in isolation (npm/fleet-env.test.js), exactly like
+// launch-config.js.
+
+// A KEY must be a POSIX-ish env identifier: a letter or underscore followed by
+// letters, digits, or underscores. dotenv / Next.js / Prisma all read this
+// shape; rejecting anything else stops a fat-fingered line from writing a
+// half-broken .env into the VM.
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+// Env-var name the fleet dashboard sets on the `cloud:up` child to name the
+// subset of `process.env` keys that came from the operator-supplied launch
+// form (`.codeyam/logs/vm-env/<n>.env`). cloud:up reads it at
+// project-bootstrap time (`npm/cloud.js::resolveSetupForwardEnv`) and
+// forwards exactly those keys into the VM's bootstrap shell — so the
+// bootstrap-time `npm run setup` has DB env on the FIRST try, instead of
+// the post-add `reapplyVmEnv` race that left `db:push` failing fail-soft.
+// One source of truth, imported on both sides — drift between dashboard
+// and cloud:up would silently disable the forwarding.
+const FORWARD_ENV_KEYS_ENV = "CY_FORWARD_ENV_KEYS";
+
+// Parse a `KEY=value`-per-line .env blob into a validated result.
+//   - Blank lines are dropped.
+//   - `#` comment lines are preserved (they carry no key).
+//   - Every other line must be `KEY=value`; only the FIRST `=` splits, so a
+//     value may itself contain `=` (e.g. a connection string) or be empty.
+//
+// Returns { ok, keys, content, error }:
+//   ok      — true when every non-blank/non-comment line parsed
+//   keys    — ordered declared keys, no values (safe to display / log)
+//   content — normalized text to write to .env (trailing newline), '' on error
+//             or when there are no keys
+//   error   — message naming the 1-based line number on failure; it NEVER
+//             echoes the line's value, so a malformed secret can't leak
+function parseEnvVars(text) {
+  const rawLines = String(text == null ? '' : text).split(/\r?\n/);
+  const fail = (error) => ({ ok: false, keys: [], content: '', error });
+  const keys = [];
+  const out = [];
+  for (let i = 0; i < rawLines.length; i += 1) {
+    const trimmed = rawLines[i].trim();
+    if (trimmed === '') continue; // drop blank lines
+    if (trimmed.startsWith('#')) { out.push(trimmed); continue; } // keep comments
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) return fail(`malformed env line ${i + 1} (expected KEY=value)`);
+    const key = trimmed.slice(0, eq).trim();
+    const value = trimmed.slice(eq + 1);
+    if (!KEY_RE.test(key)) {
+      return fail(`invalid env key on line ${i + 1} (must match [A-Za-z_][A-Za-z0-9_]*)`);
+    }
+    if (keys.includes(key)) return fail(`duplicate env key "${key}" on line ${i + 1}`);
+    keys.push(key);
+    out.push(`${key}=${value}`);
+  }
+  return { ok: true, keys, content: keys.length ? `${out.join('\n')}\n` : '', error: null };
+}
+
+// Keys only, for masked display / pre-fill — never returns values. Best-effort:
+// returns [] for unparseable input rather than throwing.
+function envKeys(text) {
+  const r = parseEnvVars(text);
+  return r.ok ? r.keys : [];
+}
+
+// True when the parsed env-text declares at least one of `triggerKeys`. Used by
+// the fleet dashboard to decide whether to re-fire `npm run setup` after
+// `/workspace/.env` lands in the container: bootstrap-time setup runs BEFORE
+// env injection, so a project whose setup needs DB env (Prisma db:push, etc.)
+// half-completes silently on first launch. Pure: takes the persisted env text
+// + the trigger list and returns a bool — no I/O, the I/O caller passes the
+// already-read text in. Unparseable input → no keys → false (matches envKeys).
+function envHasSetupTrigger(text, triggerKeys) {
+  if (!Array.isArray(triggerKeys) || triggerKeys.length === 0) return false;
+  const declared = new Set(envKeys(text));
+  return triggerKeys.some((k) => declared.has(k));
+}
+
+// Parse a `KEY=value`-per-line .env blob into a `{KEY: value}` dict suitable
+// for spreading into a child-process env. Returns null for unparseable input
+// (matches envKeys's best-effort shape so callers can fall back without
+// re-handling parse failures). Comment lines are dropped. The fleet dashboard
+// uses this to read a VM's persisted env file (`.codeyam/logs/vm-env/<n>.env`)
+// at `cloud:up`-launch time so the bootstrap-time `npm run setup` already has
+// DB env on first try — instead of the post-add `reapplyVmEnv` race where
+// setup fails fail-soft for lack of `DATABASE_URL`.
+function envToDict(text) {
+  const r = parseEnvVars(text);
+  if (!r.ok) return null;
+  const dict = {};
+  for (const line of r.content.split('\n')) {
+    if (line === '' || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    dict[line.slice(0, eq)] = line.slice(eq + 1);
+  }
+  return dict;
+}
+
+// Wrap a parsed launch-form env dict in the cloud:up bootstrap-child-env
+// shape: spreads `envDict` so the keys land in the child's `process.env`, and
+// sets `CY_FORWARD_ENV_KEYS` to the comma-separated key list so
+// `npm/cloud.js::resolveSetupForwardEnv` can whitelist exactly those keys
+// when forwarding into the VM's bootstrap shell. Returns null on empty input
+// so the dashboard's `startJob` call can omit `env` entirely (preserving
+// `process.env` inheritance for the no-launch-form-env path). A non-object
+// (programmer error) also returns null rather than throwing.
+function buildBootstrapChildEnv(envDict) {
+  if (!envDict || typeof envDict !== "object") return null;
+  const keys = Object.keys(envDict);
+  if (keys.length === 0) return null;
+  return { ...envDict, [FORWARD_ENV_KEYS_ENV]: keys.join(",") };
+}
+
+module.exports = {
+  parseEnvVars,
+  envKeys,
+  envHasSetupTrigger,
+  envToDict,
+  buildBootstrapChildEnv,
+  FORWARD_ENV_KEYS_ENV,
+  KEY_RE,
+};

package/npm/fleet-grouping.js

@@ -0,0 +1,56 @@
+// Group an already-sorted/filtered VM list by client project for the Fleet
+// Dashboard's grouped layout.
+//
+// Returns an ORDERED array of { project, vms } groups: real project groups
+// first, sorted case-insensitively by name (locale compare); the
+// unknown/starting-up bucket (project === null) pinned LAST. Within each group
+// the incoming order of `vms` is preserved untouched, so the caller's active
+// Sort mode continues to drive within-group order — grouping never re-sorts the
+// cards, it only partitions them.
+//
+// `projectKey(v)` resolves the group key for a VM and defaults to the same
+// identity `card()` renders in the dashboard:
+//   (v.cardIdentity && v.cardIdentity.project) || v.project || null
+// It is injectable so unit tests can drive grouping without constructing full
+// card payloads. A null/empty key routes the VM into the trailing unknown
+// bucket so VMs mid-provision (blank identity) never silently disappear.
+//
+// Pure; no I/O.
+
+function defaultProjectKey(v) {
+  return (v && v.cardIdentity && v.cardIdentity.project) || (v && v.project) || null;
+}
+
+function groupVmsByProject(vms, projectKey = defaultProjectKey) {
+  // First pass: stable bucketing. `Map` preserves insertion order, so the
+  // first VM of each project fixes that group's relative position before we
+  // re-order — but we re-sort named groups below regardless, so insertion
+  // order only matters for tie-stability within equal-name groups (none here).
+  const named = new Map();
+  let unknown = null;
+
+  for (const v of vms) {
+    const raw = projectKey(v);
+    const key = raw == null || raw === "" ? null : raw;
+    if (key === null) {
+      if (!unknown) unknown = { project: null, vms: [] };
+      unknown.vms.push(v);
+      continue;
+    }
+    let group = named.get(key);
+    if (!group) {
+      group = { project: key, vms: [] };
+      named.set(key, group);
+    }
+    group.vms.push(v);
+  }
+
+  const groups = Array.from(named.values());
+  groups.sort((a, b) =>
+    a.project.localeCompare(b.project, undefined, { sensitivity: "base" })
+  );
+  if (unknown) groups.push(unknown);
+  return groups;
+}
+
+module.exports = { groupVmsByProject, defaultProjectKey };

package/npm/fleet-job-badge.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// npm/fleet-job-badge.js — pure verdict for the fleet dashboard's failed-job
+// badge reconciliation (improve39). A VM's last terminal-error heavy job
+// (add/error, reset-all error, reset-editor error, …) used to stick on the
+// dashboard card indefinitely — even after the VM was recovered and is healthy
+// again — because the card renders the last job's error with no check against
+// the VM's live state, so a recovered VM keeps screaming a red error and
+// misleads the operator. This decides whether such a badge should be RECONCILED
+// (presented as "recovered" rather than a live error) because the VM is
+// demonstrably fine now. The live signals are gathered in server.js (the
+// untestable server shell); the verdict lives here so the cases are unit-tested
+// without a live VM.
+
+// Should the VM's last terminal-error job badge be reconciled against live
+// health — i.e. presented as "recovered" rather than a live red error?
+//
+//   job        the carried job record ({ state, action, ... }) or null
+//   reachable  the VM's editor answered this poll (true = healthy / responding)
+//   drifted    a project-dir-drift signal is present (reachable-but-unwired /
+//              half-provisioned add — genuinely needs-recovery, owned by the
+//              companion reconcile-inflight-jobs plan; never falsely cleared here)
+//   offBranch  the VM's live client branch differs from its target branch
+//   degraded   the job completed but a wiring sub-step is flagged degraded
+//
+// Returns true only when the job is a terminal error AND the VM is demonstrably
+// fine (reachable, not drifted, on-branch, not degraded). An unreachable /
+// drifted / off-branch VM keeps its error surfaced — a real problem must stay
+// visible.
+function shouldReconcileFailedBadge({ job, reachable, drifted, offBranch, degraded } = {}) {
+  if (!job || job.state !== 'error') return false;
+  if (!reachable) return false;
+  if (drifted) return false;
+  if (offBranch) return false;
+  if (degraded) return false;
+  return true;
+}
+
+// Given a reconcile verdict (from shouldReconcileFailedBadge) and whether the VM
+// is now idle, decide whether the recovered badge should be FULLY CLEARED — the
+// job entry dropped from state.jobs so the card goes clean — rather than merely
+// muted as a "recovered (was: …)" note (improve41).
+//
+//   badgeReconciled  the shouldReconcileFailedBadge verdict for this VM
+//   idle             the VM answered this poll, is not running a build session,
+//                    and its broker is not actively serving an agent
+//
+// A recovered VM that is also idle has demonstrably finished recovering, so the
+// stale error is dropped entirely. A recovered-but-not-yet-idle VM (mid-build,
+// or a poll hasn't confirmed idle) keeps the muted note so the prior log stays
+// visible during that transient window. Never clears a badge that wasn't first
+// judged recovered — an unreachable / drifted / off-branch error stays surfaced.
+function shouldClearReconciledBadge({ badgeReconciled, idle } = {}) {
+  return !!badgeReconciled && !!idle;
+}
+
+// Pure guard for the operator "Clear badge" action (improve41). Decides whether
+// VM-n's persisted job entry may be dropped after an out-of-band recovery,
+// independent of the server's state / fs I/O so the cases are unit-tested
+// without a live dashboard. The shell (server.js) supplies the live signals and
+// turns the verdict into the {ok,msg} response + the actual delete + snapshot.
+//
+//   rostered  the VM number is in the live roster
+//   job       the carried job record ({ state, ... }) or null/undefined
+//
+// Only a TERMINAL job (error/done) on a rostered VM may be cleared, OR a terminal
+// failed add (add/error) on a non-rostered VM (which deletes the card + add-N sidecar):
+// any other job state / non-rostered combination is not clearable.
+// Returns { ok, reason, cleanup } — reason is a stable code the shell maps to an
+// operator message, and cleanup is the cleanup action to perform ('add-failed' vs 'badge-only').
+function canClearBadge({ rostered, job } = {}) {
+  if (!rostered) {
+    if (job && job.action === 'add' && job.state === 'error') {
+      return { ok: true, reason: null, cleanup: 'add-failed' };
+    }
+    return { ok: false, reason: 'not-rostered' };
+  }
+  if (!job) return { ok: false, reason: 'no-badge' };
+  if (job.state !== 'error' && job.state !== 'done') return { ok: false, reason: 'job-active' };
+  return { ok: true, reason: null, cleanup: 'badge-only' };
+}
+
+module.exports = { shouldReconcileFailedBadge, shouldClearReconciledBadge, canClearBadge };

package/npm/fleet-memory.js

@@ -0,0 +1,157 @@
+'use strict';
+// Pure helpers for the fleet dashboard's memory-aware drain + state-snapshot
+// recovery (scripts/operator/fleet-dashboard/server.js requires this). The
+// drain threshold check, snapshot envelope serialization, freshness check, and
+// the running→error downgrade applied on restore all live here so server.js's
+// orchestration stays thin and these pieces can be unit-tested in isolation
+// (npm/fleet-memory.test.js).
+//
+// Defense in depth (improve37): the launchd plist caps the dashboard at 2GB
+// RSS; this module's drain refuses NEW heavy jobs at 1.5GB (soft cap) so RSS
+// can recover before the hard cap fires SIGKILL; the snapshot is the recovery
+// rail when the hard cap fires anyway (or launchd reloads). The pure helpers
+// here are the testable surface — server.js wires the I/O (setInterval, file
+// reads/writes, process.memoryUsage()).
+
+// Defaults the dashboard can override via env. Kept here so a test can assert
+// against the same numbers the dashboard ships with.
+const MEMORY_DEFAULTS = Object.freeze({
+  drainThresholdMB: 1500,
+  drainCheckIntervalMs: 5000,
+  snapshotIntervalMs: 30_000,
+  snapshotMaxAgeMs: 5 * 60 * 1000,
+});
+
+/** Should the dashboard refuse to admit new heavy jobs?
+ *
+ *  Returns true when current RSS exceeds the soft drain threshold. A non-
+ *  positive or non-finite threshold disables the drain (returns false) — a
+ *  misconfigured env var degrades to "no drain" instead of silently rejecting
+ *  every heavy job. Bytes on both sides so the caller doesn't have to pick a
+ *  unit; server.js passes MB→bytes once at module init.
+ *
+ *  Pure; no I/O. */
+function decideMemoryDrain({ rssBytes, drainThresholdBytes } = {}) {
+  const rss = Number(rssBytes);
+  const cap = Number(drainThresholdBytes);
+  if (!Number.isFinite(cap) || cap <= 0) return false;
+  if (!Number.isFinite(rss) || rss < 0) return false;
+  return rss > cap;
+}
+
+/** Build the serialized state snapshot envelope.
+ *
+ *  Keeps only the fields the dashboard needs to recover after a launchd
+ *  respawn: in-flight jobs, last VM poll merge, operator-visible orphans.
+ *  Times come from the caller so the same input yields the same output
+ *  (snapshot equality testable). Pure; no I/O. */
+function buildStateSnapshot({ jobs, vms, orphans, nowIso }) {
+  return {
+    version: 1,
+    timestamp: nowIso,
+    jobs: jobs || {},
+    vms: vms || {},
+    orphans: orphans || {},
+  };
+}
+
+/** Parse a buffer/string into a snapshot, or return null on any failure.
+ *  Best-effort: a corrupt or partial file (mid-write crash) is silently
+ *  treated as "no snapshot", which is the safer default than throwing on
+ *  boot. */
+function decodeStateSnapshot(buf) {
+  if (buf == null) return null;
+  try {
+    const obj = JSON.parse(typeof buf === 'string' ? buf : buf.toString('utf8'));
+    if (!obj || typeof obj !== 'object') return null;
+    if (typeof obj.timestamp !== 'string') return null;
+    return obj;
+  } catch { return null; }
+}
+
+/** Reconcile a restored snapshot into a usable starting state.
+ *
+ *  Returns null when the snapshot is missing, malformed, or older than
+ *  maxAgeMs (stale snapshots are worse than no snapshot — pollVMs will
+ *  repopulate from real data). Otherwise returns { jobs, vms, orphans }
+ *  with these safety transforms applied to jobs:
+ *
+ *    • `running` WITH a pending-job sidecar → `recovering` with a deferral
+ *      marker, NOT `error`. A heavy job that stashed a recoverable sidecar
+ *      (its cfg) must defer its final state to the startup reap, which
+ *      actually checks gcloud — the blanket `error` was the improve39 VM-7
+ *      bug: a mid-add restart stranded an instance that was really up as a
+ *      dead `add-failed`. `recovering` is an honest "the reap will resolve
+ *      this" surface; the reap then supersedes it (reconcile/half-provisioned
+ *      /cleanup) once it has the gcloud verdict.
+ *    • `running` WITHOUT a sidecar → `error` with a log marker, because the
+ *      child process died with the dashboard and there's nothing to recover
+ *      from — un-recoverable history, the old behavior.
+ *    • `queued`  → dropped, because the in-memory pendingJobQueue array
+ *      is gone, so promoteFromJobQueue can never start them. The operator
+ *      will re-click (the queued click had done no work yet).
+ *
+ *  `sidecarKeys` is the set of `${action}-${n}` strings the caller read from
+ *  the pending-jobs dir (server.js passes it; tests pass a plain array/Set).
+ *  Omitted → no job has a sidecar → every running job downgrades to `error`
+ *  exactly as before, so existing callers/tests are unaffected.
+ *
+ *  Pure; no I/O. */
+function restoreFromSnapshot({ snapshot, maxAgeMs, nowIso, sidecarKeys } = {}) {
+  if (!snapshot || typeof snapshot !== 'object') return null;
+  if (typeof snapshot.timestamp !== 'string') return null;
+  const ts = Date.parse(snapshot.timestamp);
+  const now = Date.parse(nowIso);
+  if (!Number.isFinite(ts) || !Number.isFinite(now)) return null;
+  const ageMs = now - ts;
+  const cap = Number(maxAgeMs);
+  if (!Number.isFinite(cap) || cap <= 0) return null;
+  if (ageMs > cap) return null;
+
+  const sidecars = sidecarKeys instanceof Set ? sidecarKeys : new Set(sidecarKeys || []);
+  const srcJobs = (snapshot.jobs && typeof snapshot.jobs === 'object') ? snapshot.jobs : {};
+  const jobs = {};
+  for (const [k, j] of Object.entries(srcJobs)) {
+    if (!j || typeof j !== 'object') continue;
+    if (j.state === 'queued') continue;
+    if (j.state === 'running') {
+      if (sidecars.has(`${j.action}-${k}`)) {
+        jobs[k] = {
+          ...j,
+          state: 'recovering',
+          log: `${j.log ? j.log + '\n' : ''}(snapshot-restored — deferring to startup reap)`,
+        };
+        continue;
+      }
+      jobs[k] = {
+        ...j,
+        state: 'error',
+        finishedAt: nowIso,
+        // improve40: mark this as a restart-orphan, NOT a genuine in-process
+        // failure. The job was `running` when the restart downgraded it and has
+        // NO sidecar to reconcile from — so the boot path must probe the VM's
+        // REAL provision state (orphanedAddsToReconcile → gcloud reap) rather
+        // than leave a dead `add-failed` badge on a VM that may have actually
+        // provisioned (the VM-7 hole). An add that failed IN-PROCESS keeps its
+        // own terminal `error` with no flag, so it is never re-probed/cleared.
+        restartOrphaned: true,
+        log: `${j.log ? j.log + '\n' : ''}(snapshot-restored — dashboard restarted before this finished)`,
+      };
+      continue;
+    }
+    jobs[k] = j;
+  }
+  return {
+    jobs,
+    vms: (snapshot.vms && typeof snapshot.vms === 'object') ? snapshot.vms : {},
+    orphans: (snapshot.orphans && typeof snapshot.orphans === 'object') ? snapshot.orphans : {},
+  };
+}
+
+module.exports = {
+  MEMORY_DEFAULTS,
+  decideMemoryDrain,
+  buildStateSnapshot,
+  decodeStateSnapshot,
+  restoreFromSnapshot,
+};

package/npm/fleet-plans.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Indexes the currently-reachable VMs by their live sessionId.
+ * @param {Array|Object} vms The merged VM states on the dashboard.
+ * @returns {Object} A map of sessionId -> VM number (n).
+ */
+function indexVmsBySessionId(vms) {
+  const map = {};
+  if (!vms) return map;
+  const list = Array.isArray(vms) ? vms : Object.values(vms);
+  for (const vm of list) {
+    if (vm && vm.sessionId && vm.n !== undefined) {
+      map[vm.sessionId] = vm.n;
+    }
+  }
+  return map;
+}
+
+/**
+ * Computes which dependencies are unsatisfied (i.e. not in the completedSlugs set).
+ * @param {string[]} dependsOn Prerequisite slugs.
+ * @param {Set|string[]} completedSlugs Set or array of completed plan slugs.
+ * @returns {string[]} The unsatisfied dependency slugs.
+ */
+function unsatisfiedDeps(dependsOn, completedSlugs) {
+  const deps = Array.isArray(dependsOn) ? dependsOn : [];
+  const completedSet = completedSlugs instanceof Set ? completedSlugs : new Set(completedSlugs || []);
+  return deps.filter(dep => !completedSet.has(dep));
+}
+
+/**
+ * Resolves claims and dependency states for each queued plan.
+ * @param {Object} params
+ * @param {Object[]} params.plans Array of PlanSummary objects from /api/plans.
+ * @param {Object[]} params.claims Array of PlanClaim objects from /api/plan-claims.
+ * @param {Set|string[]} params.completedSlugs Completed plan slugs.
+ * @param {Object} params.vmsBySessionId Map of sessionId -> VM number.
+ * @returns {Object[]} Annotated plan rows.
+ */
+function resolvePlanRows({ plans, claims, completedSlugs, vmsBySessionId }) {
+  const list = Array.isArray(plans) ? plans : [];
+  const claimsList = Array.isArray(claims) ? claims : [];
+
+  return list.map(plan => {
+    // 1. Extract plan fields
+    const slug = plan.slug;
+    const title = plan.title;
+    const mode = plan.mode || null;
+    const order = plan.order != null ? plan.order : null;
+    const prefix = plan.prefix || null;
+
+    // 2. Resolve dependency-blocked state
+    const dependsOn = Array.isArray(plan.depends_on) ? plan.depends_on : (plan.dependsOn ? plan.dependsOn : []);
+    const blockedBy = unsatisfiedDeps(dependsOn, completedSlugs);
+
+    // 3. Resolve claim state
+    const claim = claimsList.find(c => c.slug === slug);
+    let claimInfo = null;
+    if (claim) {
+      const claimedBy = claim.claimedBy || claim.claimed_by || {};
+      const sessionId = claimedBy.sessionId || claimedBy.session_id || null;
+      const vm = (sessionId && vmsBySessionId && vmsBySessionId[sessionId] !== undefined) ? vmsBySessionId[sessionId] : null;
+      
+      claimInfo = {
+        vm,
+        machine: claimedBy.machine || null,
+        agent: claimedBy.agentProvider || claimedBy.agent_provider || null,
+        sessionAlive: claim.sessionAlive !== undefined ? claim.sessionAlive : (claim.session_alive !== undefined ? claim.session_alive : null),
+        source: claim.source || null,
+        currentStep: claimedBy.currentStep || claimedBy.current_step || null,
+      };
+    }
+
+    return {
+      slug,
+      title,
+      mode,
+      order,
+      prefix,
+      blockedBy,
+      claim: claimInfo
+    };
+  });
+}
+
+const REQUIRED_PLAN_ROW_FIELDS = [
+  'slug', 'title', 'mode', 'order', 'prefix', 'blockedBy', 'claim'
+];
+
+module.exports = {
+  indexVmsBySessionId,
+  unsatisfiedDeps,
+  resolvePlanRows,
+  REQUIRED_PLAN_ROW_FIELDS
+};

package/npm/fleet-pool-policy.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// npm/fleet-pool-policy.js — the warm pool's cost-control policy (improve38).
+//
+// Idle pool VMs cost money, so the pool's target size is not a constant — it's
+// a function of the clock. During working hours the keeper holds `baseSize`
+// claim-ready VMs; off-hours (and on an idle timer) it scales the target down,
+// by default to zero, so an overnight pool doesn't bill for VMs nobody will
+// claim. A claim against the resulting empty pool falls back to on-demand
+// `fleet-ready` (slower, but it works) rather than failing — so scaling to zero
+// is safe, not a service outage.
+//
+// This is the pure decision half, kept out of the keeper's untestable SSH loop:
+// given a config and a clock, what should the pool target be right now? The
+// keeper reads the answer and provisions/evicts toward it.
+
+// Resolve the pool config from an env-like object (process.env in production,
+// a literal in tests), applying defaults. All knobs are operator-tunable so the
+// same keeper serves a 0-VM hobby fleet and a 20-VM team pool with no code
+// change.
+//   POOL_TARGET            base (working-hours) pool size           default 4
+//   POOL_OFFHOURS_TARGET   pool size during off-hours               default 0
+//   POOL_OFFHOURS_START    hour [0-23] off-hours begin (inclusive)  default 20
+//   POOL_OFFHOURS_END      hour [0-23] off-hours end   (exclusive)  default 8
+// A start==end disables the off-hours window entirely (always baseSize).
+function resolveConfig(env) {
+  const e = env || {};
+  return {
+    baseSize: intOr(e.POOL_TARGET, 4),
+    offHoursSize: intOr(e.POOL_OFFHOURS_TARGET, 0),
+    offHoursStart: clampHour(e.POOL_OFFHOURS_START, 20),
+    offHoursEnd: clampHour(e.POOL_OFFHOURS_END, 8),
+  };
+}
+
+// Non-negative integer or the default. Sizes can't be negative, so a negative
+// (or non-numeric) value is rejected to the default rather than silently used.
+function intOr(v, dflt) {
+  const n = Number(v);
+  return Number.isInteger(n) && n >= 0 ? n : dflt;
+}
+
+// Parse an hour into [0, 23], clamping out-of-range values both directions
+// (a negative → 0, a too-large → 23) so a typo'd config indexes a real hour
+// instead of wedging the window. A non-numeric value falls back to `dflt`.
+function clampHour(v, dflt) {
+  const n = Number(v);
+  if (!Number.isInteger(n)) return dflt;
+  if (n < 0) return 0;
+  if (n > 23) return 23;
+  return n;
+}
+
+// Is `hour` within the off-hours window [start, end)? The window wraps midnight
+// when start > end (the common case: 20:00 → 08:00 spans the night). start==end
+// means "no off-hours window" → always false.
+function isOffHours(hour, start, end) {
+  if (start === end) return false;
+  if (start < end) return hour >= start && hour < end; // same-day window
+  return hour >= start || hour < end; // wraps midnight
+}
+
+// The pool target size for the given clock: offHoursSize inside the off-hours
+// window, baseSize otherwise. `date` is a Date (defaults to now) — the local
+// hour drives the decision, matching the operator's working day.
+function desiredPoolSize(config, date) {
+  const cfg = config && typeof config.baseSize === 'number' ? config : resolveConfig(config);
+  const d = date || new Date();
+  return isOffHours(d.getHours(), cfg.offHoursStart, cfg.offHoursEnd)
+    ? cfg.offHoursSize
+    : cfg.baseSize;
+}
+
+module.exports = {
+  resolveConfig,
+  isOffHours,
+  desiredPoolSize,
+};