@codeyam-editor/codeyam-editor 0.1.1 → 0.1.2

package/npm/fleet-auth.js

@@ -0,0 +1,111 @@
+'use strict';
+// Pure helpers for the fleet dashboard's "Authenticate idle VMs" batch flow
+// (scripts/operator/fleet-dashboard/server.js requires this). The decision of
+// WHICH VMs a fleet-auth pass touches — and how to summarize an in-flight
+// batch — lives here so server.js's HTTP orchestration stays thin and the
+// guardrail logic is unit-testable in isolation (npm/fleet-auth.test.js).
+//
+// Why per-VM real `claude /login` and not one shared credential: copying a
+// `.credentials.json` between VMs 401s (Claude rotates/binds the OAuth access
+// token to its originating VM), and the `CLAUDE_CODE_OAUTH_TOKEN` setup-token
+// is limited-scope + non-durable (lost on container recreate). So every VM
+// needs its own interactive login — this batches the human step across the
+// fleet (start every idle VM's login in parallel, approve them as one list)
+// instead of distributing a single token. See docs/cloud-editor-stability.md
+// "Fleet auth".
+
+// Classify one VM for the fleet-auth pass. Returns { eligible, reason }.
+//
+// The guardrail mirrors Destroy / Reconfigure / roll: NEVER touch an active
+// session (a mid-build agent must not have its editor driven into a login
+// PTY), and never start an auth pass on a VM that already has a running or
+// queued job. Only a reachable, idle VM the editor reports as `needs-login` is
+// a target. An `unknown` / absent auth state is deliberately NOT a target —
+// the probe is indeterminate (a transient failure on an otherwise-healthy VM),
+// and driving a login we can't confirm is needed risks disrupting a working
+// VM. `v` is the dashboard's per-VM poll state (`state.vms[n]`); `job` is
+// `state.jobs[n]` (may be undefined).
+function classifyAuthVm(v, job) {
+  if (job && (job.state === 'running' || job.state === 'queued')) {
+    return { eligible: false, reason: 'busy' };
+  }
+  if (!v || !v.reachable) return { eligible: false, reason: 'unreachable' };
+  if (v.hasSession) return { eligible: false, reason: 'active-session' };
+  const state = v.providerAuth && v.providerAuth.state;
+  if (state === 'authenticated') return { eligible: false, reason: 'already-authenticated' };
+  if (state === 'needs-login') return { eligible: true, reason: 'needs-login' };
+  return { eligible: false, reason: 'auth-state-unknown' };
+}
+
+// Select every VM the fleet-auth pass should drive a login on, plus the
+// skipped VMs each with the reason it was excluded (surfaced to the operator
+// so "why didn't VM-7 get authenticated?" is answerable without ssh).
+//
+// roster: number[] (the live VMS array). vms / jobs: maps keyed by VM number.
+// Returns { targets: number[], skipped: [{ n, reason }] }, both sorted by n.
+function selectAuthTargets({ roster, vms, jobs }) {
+  const targets = [];
+  const skipped = [];
+  for (const n of [...(roster || [])].sort((a, b) => a - b)) {
+    const c = classifyAuthVm((vms || {})[n], (jobs || {})[n]);
+    if (c.eligible) targets.push(n);
+    else skipped.push({ n, reason: c.reason });
+  }
+  return { targets, skipped };
+}
+
+// Aggregate an in-flight batch (map of n → { phase }) into counts for the
+// operator report. Phases mirror the editor's /api/auth/status states
+// ('starting' | 'url-ready' | 'authenticated' | 'failed') plus the
+// dashboard-side 'submitting' while a pasted code is being delivered. Pure
+// over the values; `done` is true once no VM is still mid-flight, which is
+// what lets the UI stop polling / show a final "N of M authenticated" line.
+function summarizeAuthBatch(batchVms) {
+  const counts = { total: 0, starting: 0, urlReady: 0, submitting: 0, authenticated: 0, failed: 0 };
+  for (const n of Object.keys(batchVms || {})) {
+    const phase = batchVms[n] && batchVms[n].phase;
+    counts.total++;
+    if (phase === 'starting') counts.starting++;
+    else if (phase === 'url-ready') counts.urlReady++;
+    else if (phase === 'submitting') counts.submitting++;
+    else if (phase === 'authenticated') counts.authenticated++;
+    else if (phase === 'failed') counts.failed++;
+  }
+  // In-flight = still starting, or awaiting a pasted code, or submitting one.
+  // A `failed` VM is terminal until the operator restarts the batch, and an
+  // `authenticated` VM is done — so neither counts as in-flight.
+  counts.inFlight = counts.starting + counts.urlReady + counts.submitting;
+  counts.done = counts.total > 0 && counts.inFlight === 0;
+  return counts;
+}
+
+// Derive the fleet's current default Claude account (improve38): the account a
+// newly launched VM should authenticate as. Defined as the account of the
+// rostered VM whose auth was updated most recently, where "auth-update time" =
+// max(dashboard-recorded login-completion `lastAuthAt[n]`, the editor-reported
+// `providerAuth.lastRefreshAt`). Re-authenticating ANY existing VM thus
+// re-points the default. Pure over the polled VM snapshot + the lastAuthAt map.
+//
+// Returns the winning VM's account object ({ email, organizationName,
+// organizationType, subscriptionType }), or null when no rostered VM reports an
+// account. Ties — and the no-timestamp case — resolve to the first such VM in
+// `vms` order, so the result is deterministic.
+function deriveDefaultAuthAccount(vms, lastAuthAt) {
+  const at = lastAuthAt || {};
+  let best = null;
+  for (const v of vms || []) {
+    const pa = v && v.providerAuth;
+    const acct = pa && pa.account;
+    if (!acct || !acct.email) continue;
+    const refreshMs = pa.lastRefreshAt ? Date.parse(pa.lastRefreshAt) : NaN;
+    const loginMs = at[v.n] ? Date.parse(at[v.n]) : NaN;
+    const score = Math.max(
+      Number.isFinite(refreshMs) ? refreshMs : -Infinity,
+      Number.isFinite(loginMs) ? loginMs : -Infinity,
+    );
+    if (!best || score > best.score) best = { account: acct, score };
+  }
+  return best ? best.account : null;
+}
+
+module.exports = { classifyAuthVm, selectAuthTargets, summarizeAuthBatch, deriveDefaultAuthAccount };

package/npm/fleet-cleanup.js

@@ -0,0 +1,124 @@
+'use strict';
+// Pure-ish helpers for the fleet dashboard's pending-job sidecar feature
+// (scripts/operator/fleet-dashboard/server.js requires this). Sidecar
+// serialization, regex parsing of filenames, gcloud-describe error
+// classification, and the reap decision matrix all live here so the
+// `server.js` orchestration code can be left thin and these pieces can be
+// exercised in isolation (npm/fleet-cleanup.test.js).
+//
+// File-touching helpers take the directory as a PARAMETER so tests pass a
+// throwaway tmpdir; the dashboard passes its fixed `PENDING_JOBS_DIR` constant.
+
+const fs = require('fs');
+const path = require('path');
+
+// Sidecar filename grammar: `<action>-<n>.json` where action ∈ {add, destroy}.
+// Returns { action, n } on a valid match, null otherwise. Hoisted out of the
+// inline regex so the parser is unit-testable on its own (junk filenames, tmp
+// turds, missing numbers).
+function parsePendingJobFilename(name) {
+  const m = String(name == null ? '' : name).match(/^(add|destroy)-(\d+)\.json$/);
+  if (!m) return null;
+  return { action: m[1], n: Number(m[2]) };
+}
+
+// Atomically write a sidecar marking VM-n's <action> in flight. Best-effort:
+// any I/O failure is logged, never thrown (the dashboard mustn't crash because
+// .codeyam/logs is missing or read-only).
+function persistPendingJob(dir, n, action, meta) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    const f = path.join(dir, `${action}-${n}.json`);
+    const tmp = f + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify({ n, action, startedAt: new Date().toISOString(), ...(meta || {}) }));
+    fs.renameSync(tmp, f);
+  } catch (e) { console.error('persistPendingJob:', e && e.message); }
+}
+
+// Remove a sidecar; a missing file is the already-cleared path, not an error.
+function clearPendingJob(dir, n, action) {
+  try { fs.unlinkSync(path.join(dir, `${action}-${n}.json`)); }
+  catch (_) { /* missing is fine */ }
+}
+
+// Enumerate sidecars under `dir`. Returns one entry per RECOGNISED file —
+// junk filenames are dropped silently so an operator's debug touch under
+// pending-jobs/ can't crash the reap. Unparseable JSON meta degrades to `{}`
+// (the sidecar's existence is what matters; meta is best-effort context).
+function listPendingJobs(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const name of entries) {
+    const parsed = parsePendingJobFilename(name);
+    if (!parsed) continue;
+    let meta = {};
+    try { meta = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8')) || {}; }
+    catch { /* unparseable — treat as bare {action, n} */ }
+    out.push({ n: parsed.n, action: parsed.action, meta });
+  }
+  return out;
+}
+
+// Classify the outcome of a `gcloud compute instances describe` exec callback.
+//   - err is null/undefined  → instance exists (`true`)
+//   - stderr/err.message names "NOT_FOUND" / "was not found" / "not found"
+//                            → instance is gone (`false`)
+//   - anything else (auth glitch, network blip, timeout) → uncertain (`null`)
+// The `null` case is what makes the reap fail-soft: an uncertain probe leaves
+// the sidecar in place so the next dashboard boot retries instead of clearing
+// state on a flaky gcloud.
+function classifyDescribeError(err, stderr) {
+  if (!err) return true;
+  const out = String(stderr == null ? '' : stderr) + ' ' + String((err && err.message) || '');
+  if (/NOT_FOUND|was not found|not found/i.test(out)) return false;
+  return null;
+}
+
+// Decide what the startup reap should do for one sidecar. Pure: takes the
+// decoded sidecar + GCP-existence verdict + (for adds) container-up verdict,
+// returns a tag the caller dispatches on.
+//   verdict             when                                          dispatch
+//   'cleanup'           destroy gone, OR add gone                     runDestroyCleanup / runAddCleanup
+//   'reconcile-add'     add up AND container up                       ensure roster + recordLaunch, then clear
+//   'recover-bootstrap' add instance up but container missing/down    re-run cloud:up to finish the half-done bootstrap
+//   'clear-only'        destroy sidecar but instance still exists     just clear the sidecar
+//   'leave'             gcloud uncertain (exists === null)             leave for the next boot
+// The (exists, containerUp) split is what distinguishes a finished add from a
+// half-provisioned one: a dashboard SIGKILL'd mid-`cloud:up` leaves a GCP
+// instance with no docker/container, which the old (exists-only) matrix wrongly
+// classified 'reconcile-add' — adding an unreachable VM to the roster.
+// `containerUp` is only consulted for an add whose instance exists; destroy and
+// the instance-gone add path ignore it. Splitting the matrix out lets the table
+// be exhaustively tested without any of the side-effects in server.js.
+function reapVerdict({ action, exists, containerUp }) {
+  if (exists === null) return 'leave';
+  if (action === 'destroy') return exists ? 'clear-only' : 'cleanup';
+  if (action === 'add') {
+    if (!exists) return 'cleanup';
+    return containerUp ? 'reconcile-add' : 'recover-bootstrap';
+  }
+  return 'leave';
+}
+
+// Anti-loop budget for the `recover-bootstrap` path. Pure: given the count of
+// recoveries ALREADY persisted on the sidecar, return the next attempt number,
+// whether the reap should proceed (re-run cloud:up) or treat the VM as
+// exhausted (leave the sidecar + surface a needs-manual-recovery card), and the
+// cap. Keeps the off-by-one (prior 3 → attempt 4 → stop) out of server.js so it
+// can be unit-tested without the side-effecting re-run.
+function recoverBootstrapDecision({ recoverAttempts, max = 3 }) {
+  const prior = Number(recoverAttempts) || 0;
+  const attempt = prior + 1;
+  return { attempt, proceed: attempt <= max, max };
+}
+
+module.exports = {
+  parsePendingJobFilename,
+  persistPendingJob,
+  clearPendingJob,
+  listPendingJobs,
+  classifyDescribeError,
+  reapVerdict,
+  recoverBootstrapDecision,
+};

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-memory.js

@@ -0,0 +1,127 @@
+'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 two safety transforms applied to jobs:
+ *
+ *    • `running` → `error` with a log marker, because the child process
+ *      died with the dashboard; we can't possibly have a live job tracker
+ *      after a process restart.
+ *    • `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).
+ *
+ *  Pure; no I/O. */
+function restoreFromSnapshot({ snapshot, maxAgeMs, nowIso } = {}) {
+  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 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') {
+      jobs[k] = {
+        ...j,
+        state: 'error',
+        finishedAt: nowIso,
+        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-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,
+};