@codeyam-editor/codeyam-editor 0.1.1 → 0.1.3

package/npm/fleet-job-badge.js

@@ -0,0 +1,39 @@
+'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;
+}
+
+module.exports = { shouldReconcileFailedBadge };

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-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,
+};

package/npm/fleet-pool.js

@@ -0,0 +1,401 @@
+'use strict';
+
+// npm/fleet-pool.js — the warm-VM-pool state layer (improve38).
+//
+// Standing up a VM on demand pays for an image pull, a branch rebrand and —
+// the slow part — an interactive auth approval. The warm pool removes that
+// latency from the request path: keep N pre-provisioned, pre-authed, READY
+// idle VMs and CLAIM them in seconds (rebrand-only, no OAuth). This module is
+// the state seam for that pool — it answers "which VMs are idle-and-claimable
+// vs already-assigned" and performs the ATOMIC claim that guarantees two
+// operators never grab the same VM.
+//
+// Why a SEPARATE file from the roster (`fleet-vms.json`): the roster is a
+// shared contract — a plain JSON array of VM-number integers that the
+// dashboard, vm-watchdog, cloudflared-monitor and the bash publishers all
+// read. Widening it to carry per-VM status would break every reader (they
+// `jq -r '.[]'` it as scalars). So pool membership lives alongside the roster
+// in `.codeyam/logs/fleet-pool.json`, keyed by VM number, and the roster keeps
+// meaning "these VM numbers exist". A VM can be in the roster without being in
+// the pool (e.g. an operator's hand-driven VM); the pool only tracks the warm
+// set.
+//
+// On-disk shape (tolerant: a missing or malformed file is the empty pool):
+//   { "vms": { "<n>": { status, branch, freshAt, claimedAt } } }
+//     status:    "pool"      idle, claim-ready
+//                "assigned"  claimed by an operator, rebranded to `branch`
+//     branch:    the branch the VM is on (base branch while pooled)
+//     freshAt:   ISO timestamp of the last successful auth/health refresh —
+//                drives evict-before-claim of a member whose token lapsed
+//     claimedAt: ISO timestamp of the claim (null while pooled)
+//
+// The pure functions (normalize / select / refill / staleness) operate on a
+// plain state object and return a new one — no I/O — so they unit-test without
+// touching disk. readState/writeState/withLock add the atomic file layer, and
+// main() is the CLI seam the bash orchestrators (fleet-claim.sh,
+// fleet-pool-keeper.sh) call instead of re-implementing the logic in shell.
+
+const fs = require('fs');
+const path = require('path');
+
+const { rootDir } = require('./utils');
+
+const POOL_STATE_FILE = process.env.POOL_STATE_FILE
+  || path.join(rootDir, '.codeyam', 'logs', 'fleet-pool.json');
+
+const POOL = 'pool';
+const ASSIGNED = 'assigned';
+
+// ── Pure state helpers ──────────────────────────────────────────────────────
+
+// Coerce arbitrary parsed JSON into the canonical `{ vms: { <n>: entry } }`
+// shape. Drops entries whose key is not a positive integer or whose status is
+// unrecognized, so a truncated write or a hand-edit never feeds a malformed
+// entry into the claim path. Returned object is a fresh copy — callers mutate
+// it freely.
+function normalizeState(raw) {
+  const out = { vms: {} };
+  const vms = raw && typeof raw === 'object' ? raw.vms : null;
+  if (!vms || typeof vms !== 'object') return out;
+  for (const key of Object.keys(vms)) {
+    const n = Number(key);
+    if (!Number.isInteger(n) || n <= 0) continue;
+    const e = vms[key] || {};
+    const status = e.status === ASSIGNED ? ASSIGNED : e.status === POOL ? POOL : null;
+    if (!status) continue;
+    out.vms[n] = {
+      status,
+      branch: typeof e.branch === 'string' ? e.branch : null,
+      freshAt: typeof e.freshAt === 'string' ? e.freshAt : null,
+      claimedAt: typeof e.claimedAt === 'string' ? e.claimedAt : null,
+    };
+  }
+  return out;
+}
+
+// VM numbers in a given status, sorted ascending. Ascending order makes claim
+// selection deterministic (lowest-numbered idle VM first) so tests and two
+// concurrent callers agree on which VM a claim takes.
+function membersByStatus(state, status) {
+  return Object.keys(state.vms)
+    .map(Number)
+    .filter((n) => state.vms[n].status === status)
+    .sort((a, b) => a - b);
+}
+
+function poolMembers(state) {
+  return membersByStatus(state, POOL);
+}
+
+function assignedMembers(state) {
+  return membersByStatus(state, ASSIGNED);
+}
+
+// True when a pool entry's auth/health is older than `ttlMs` (its token may
+// have lapsed). An entry with no `freshAt` is treated as stale — "freshness
+// not proven" fails closed, mirroring fleet-ready's auth gate. Only meaningful
+// for pooled VMs; an assigned VM is the operator's concern, not the keeper's.
+function isStale(entry, nowMs, ttlMs) {
+  if (!entry || entry.status !== POOL) return false;
+  if (!entry.freshAt) return true;
+  const t = Date.parse(entry.freshAt);
+  if (Number.isNaN(t)) return true;
+  return nowMs - t > ttlMs;
+}
+
+// Pool VM numbers whose freshness has lapsed — the evict-before-claim set the
+// keeper drops (and replaces) so a claim never hands a caller a stale VM.
+function staleMembers(state, nowMs, ttlMs) {
+  return poolMembers(state).filter((n) => isStale(state.vms[n], nowMs, ttlMs));
+}
+
+// How many NEW pool VMs the keeper must provision to reach `target` idle
+// members. Assigned VMs do not count toward the pool — once claimed they're
+// gone from the warm set until released — so a claim naturally triggers a
+// refill. Never negative (an over-target pool is shrunk by policy, not here).
+function refillCount(state, target) {
+  const have = poolMembers(state).length;
+  return Math.max(0, target - have);
+}
+
+// The heart of the claim: deterministically move up to `count` idle pool VMs to
+// `assigned` on `branch`. Pure — returns { next, claimed, shortfall } without
+// touching disk; the caller persists `next` under the lock. Lowest-numbered
+// VMs are taken first. `shortfall` (requested minus granted) is the signal the
+// orchestrator uses to fall back to on-demand provisioning when the pool can't
+// satisfy the whole request — an empty pool yields claimed=[] , shortfall=count
+// rather than an error.
+function selectForClaim(state, count, branch, nowIso) {
+  const next = normalizeState(state);
+  const idle = poolMembers(next);
+  const take = idle.slice(0, Math.max(0, count));
+  for (const n of take) {
+    next.vms[n] = {
+      ...next.vms[n],
+      status: ASSIGNED,
+      branch,
+      claimedAt: nowIso,
+    };
+  }
+  return { next, claimed: take, shortfall: Math.max(0, count - take.length) };
+}
+
+// Register (or overwrite) a VM in the pool state. The keeper calls this after
+// provisioning a fresh READY VM (status=pool) and the claim path can re-add an
+// assigned VM. `freshAt` defaults to now for a pool member so a just-verified
+// VM isn't immediately stale.
+function applyAdd(state, n, status, branch, nowIso) {
+  const next = normalizeState(state);
+  const st = status === ASSIGNED ? ASSIGNED : POOL;
+  next.vms[n] = {
+    status: st,
+    branch: branch || null,
+    freshAt: st === POOL ? nowIso : (next.vms[n] && next.vms[n].freshAt) || null,
+    claimedAt: st === ASSIGNED ? nowIso : null,
+  };
+  return next;
+}
+
+// Return an assigned VM to the idle pool (operator finished with it). A no-op
+// for an absent VM. `freshAt` is reset to now: a just-released VM was live and
+// authed, so it's claim-ready again without waiting for the keeper's refresh.
+function applyRelease(state, n, nowIso) {
+  const next = normalizeState(state);
+  if (!next.vms[n]) return next;
+  next.vms[n] = {
+    ...next.vms[n],
+    status: POOL,
+    freshAt: nowIso,
+    claimedAt: null,
+  };
+  return next;
+}
+
+// Drop a VM from the pool state entirely (the keeper evicts a stale/unhealthy
+// member before replacing it). A no-op for an absent VM.
+function applyEvict(state, n) {
+  const next = normalizeState(state);
+  delete next.vms[n];
+  return next;
+}
+
+// Stamp a pool member as freshly auth/health-verified. The keeper calls this
+// after a successful credential refresh so the member's eviction clock resets.
+function applyMarkFresh(state, n, nowIso) {
+  const next = normalizeState(state);
+  if (!next.vms[n]) return next;
+  next.vms[n] = { ...next.vms[n], freshAt: nowIso };
+  return next;
+}
+
+// ── Atomic file layer ───────────────────────────────────────────────────────
+
+// Synchronous millisecond sleep without a busy CPU spin — used by withLock's
+// retry. Atomics.wait blocks the (single) thread for `ms`; a fresh 4-byte
+// SharedArrayBuffer that nothing else holds means the wait always times out
+// rather than being woken early.
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// Run `fn` while holding a cross-PROCESS mutex around the pool-state file, so a
+// read-modify-write (the claim) is atomic even when two operators run
+// `fleet-claim` at the same moment. The lock is a directory next to the state
+// file: `mkdir` is atomic on POSIX, so exactly one process wins the create and
+// the rest retry. A lock older than `staleMs` is assumed abandoned (a crashed
+// claimer) and stolen, so a dead process can't wedge the pool forever.
+function withLock(fn, { retries = 100, delayMs = 25, staleMs = 30000 } = {}) {
+  const lockDir = `${POOL_STATE_FILE}.lock`;
+  fs.mkdirSync(path.dirname(POOL_STATE_FILE), { recursive: true });
+  let held = false;
+  for (let i = 0; i < retries && !held; i += 1) {
+    try {
+      fs.mkdirSync(lockDir);
+      held = true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      // Steal an abandoned lock (claimer crashed mid-operation).
+      try {
+        const age = Date.now() - fs.statSync(lockDir).mtimeMs;
+        if (age > staleMs) {
+          fs.rmdirSync(lockDir);
+          continue; // retry the mkdir immediately
+        }
+      } catch { /* lock vanished between stat and now — just retry */ }
+      sleepSync(delayMs);
+    }
+  }
+  if (!held) throw new Error(`fleet-pool: could not acquire lock ${lockDir} after ${retries} tries`);
+  try {
+    return fn();
+  } finally {
+    try { fs.rmdirSync(lockDir); } catch { /* already gone */ }
+  }
+}
+
+// Read + normalize the pool state. A missing or malformed file is the empty
+// pool `{ vms: {} }` (the documented tolerant contract), so a truncated write
+// never throws into the keeper's reconcile loop.
+function readState() {
+  try {
+    return normalizeState(JSON.parse(fs.readFileSync(POOL_STATE_FILE, 'utf8')));
+  } catch {
+    return { vms: {} };
+  }
+}
+
+// Persist `state` atomically: write a pid-tagged temp file then `rename` over
+// the target so a concurrent reader never observes a half-written file (same
+// discipline as fleet-roster.writeRoster). Returns the normalized state.
+function writeState(state) {
+  const next = normalizeState(state);
+  fs.mkdirSync(path.dirname(POOL_STATE_FILE), { recursive: true });
+  const tmp = `${POOL_STATE_FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(next));
+  fs.renameSync(tmp, POOL_STATE_FILE);
+  return next;
+}
+
+module.exports = {
+  POOL_STATE_FILE,
+  POOL,
+  ASSIGNED,
+  normalizeState,
+  poolMembers,
+  assignedMembers,
+  isStale,
+  staleMembers,
+  refillCount,
+  selectForClaim,
+  applyAdd,
+  applyRelease,
+  applyEvict,
+  applyMarkFresh,
+  withLock,
+  readState,
+  writeState,
+  main,
+};
+
+// ── CLI seam ────────────────────────────────────────────────────────────────
+// The bash orchestrators call these subcommands instead of re-deriving the
+// logic in shell. Each mutating subcommand runs its read-modify-write inside
+// withLock so concurrent callers serialize. Output is line-oriented and
+// machine-parseable (space-separated VM numbers / a single integer) so the
+// shell side stays a thin `$(node fleet-pool.js ...)` capture.
+
+function parsePoolFlags(argv) {
+  const flags = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[(i += 1)] : 'true';
+      flags[key] = val;
+    }
+  }
+  return flags;
+}
+
+function main(argv) {
+  const [cmd, ...rest] = argv;
+  const flags = parsePoolFlags(rest);
+  const now = flags.now || new Date().toISOString();
+
+  switch (cmd) {
+    case 'list':
+      process.stdout.write(`${JSON.stringify(readState(), null, 2)}\n`);
+      return 0;
+    case 'pool-members':
+      process.stdout.write(`${poolMembers(readState()).join(' ')}\n`);
+      return 0;
+    case 'assigned-members':
+      process.stdout.write(`${assignedMembers(readState()).join(' ')}\n`);
+      return 0;
+    case 'refill-count': {
+      const target = Number(flags.target);
+      if (!Number.isInteger(target) || target < 0) {
+        process.stderr.write('fleet-pool: refill-count needs --target <non-negative int>\n');
+        return 2;
+      }
+      process.stdout.write(`${refillCount(readState(), target)}\n`);
+      return 0;
+    }
+    case 'stale': {
+      const ttl = Number(flags['ttl-seconds']);
+      if (!Number.isInteger(ttl) || ttl < 0) {
+        process.stderr.write('fleet-pool: stale needs --ttl-seconds <non-negative int>\n');
+        return 2;
+      }
+      const out = staleMembers(readState(), Date.parse(now), ttl * 1000);
+      process.stdout.write(`${out.join(' ')}\n`);
+      return 0;
+    }
+    case 'claim': {
+      const count = Number(flags.count);
+      const branch = flags.branch;
+      if (!Number.isInteger(count) || count <= 0 || !branch || branch === 'true') {
+        process.stderr.write('fleet-pool: claim needs --count <pos int> --branch <name>\n');
+        return 2;
+      }
+      const result = withLock(() => {
+        const { next, claimed, shortfall } = selectForClaim(readState(), count, branch, now);
+        writeState(next);
+        return { claimed, shortfall };
+      });
+      // VM numbers on stdout (the orchestrator rebrands each); shortfall on
+      // stderr so an empty/short pool is visible without polluting the capture.
+      process.stdout.write(`${result.claimed.join(' ')}\n`);
+      if (result.shortfall > 0) {
+        process.stderr.write(`fleet-pool: shortfall ${result.shortfall} (pool could not satisfy full claim)\n`);
+      }
+      return 0;
+    }
+    case 'add': {
+      const vm = Number(flags.vm);
+      if (!Number.isInteger(vm) || vm <= 0) {
+        process.stderr.write('fleet-pool: add needs --vm <pos int>\n');
+        return 2;
+      }
+      const status = flags.status === ASSIGNED ? ASSIGNED : POOL;
+      withLock(() => writeState(applyAdd(readState(), vm, status, flags.branch, now)));
+      return 0;
+    }
+    case 'release': {
+      const vm = Number(flags.vm);
+      if (!Number.isInteger(vm) || vm <= 0) {
+        process.stderr.write('fleet-pool: release needs --vm <pos int>\n');
+        return 2;
+      }
+      withLock(() => writeState(applyRelease(readState(), vm, now)));
+      return 0;
+    }
+    case 'evict': {
+      const vm = Number(flags.vm);
+      if (!Number.isInteger(vm) || vm <= 0) {
+        process.stderr.write('fleet-pool: evict needs --vm <pos int>\n');
+        return 2;
+      }
+      withLock(() => writeState(applyEvict(readState(), vm)));
+      return 0;
+    }
+    case 'mark-fresh': {
+      const vm = Number(flags.vm);
+      if (!Number.isInteger(vm) || vm <= 0) {
+        process.stderr.write('fleet-pool: mark-fresh needs --vm <pos int>\n');
+        return 2;
+      }
+      withLock(() => writeState(applyMarkFresh(readState(), vm, now)));
+      return 0;
+    }
+    default:
+      process.stderr.write(
+        'fleet-pool: usage: <list|pool-members|assigned-members|refill-count|stale|claim|add|release|evict|mark-fresh> [--flags]\n',
+      );
+      return 2;
+  }
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}