@codeyam-editor/codeyam-editor 0.1.1 → 0.1.2

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

package/npm/fleet-queue.js

@@ -0,0 +1,40 @@
+'use strict';
+// Pure helpers for the fleet dashboard's commit-queue auto-release logic
+// (scripts/operator/fleet-dashboard/server.js requires this). The decision
+// of whether to auto-release a queue head lives here so server.js's
+// orchestration stays thin and this piece can be unit-tested in isolation
+// (npm/fleet-queue.test.js).
+//
+// Auto-release fires only on the deterministic "owning VM left the fleet"
+// signal — a VM that is absent from the roster AND has no in-flight
+// provisioning job. The ambiguous "in roster but unreachable" case is
+// explicitly out of scope: a transient blip could trigger a spurious
+// release. That case is surfaced as a badge for the operator to act on.
+
+/** Decide whether the current queue head should be auto-released.
+ *
+ *  Conditions that must ALL hold:
+ *    1. The head entry's `vm` field is non-null (the machine name matched the
+ *       fleet's INSTANCE_PREFIX-…-<n> shape via vmFromMachine). An
+ *       unattributable head (vm===null) is never auto-released.
+ *    2. That VM number is absent from the live `vms` roster array.
+ *    3. There is no in-flight or queued provisioning job for that number
+ *       (guards the Add→addVm gap where a VM is being created but not yet
+ *       rostered). Also guards known-orphan VM numbers.
+ *
+ *  Returns { release: false } or { release: true, uuid, vm, reason }.
+ *  Pure; no I/O.
+ */
+function decideAutoReleaseGoneHead({ queue, vms, jobs, orphans }) {
+  const head = queue && queue[0];
+  if (!head || head.vm == null) return { release: false };
+  const n = head.vm;
+  if (vms.includes(n)) return { release: false };
+  const job = jobs[n];
+  const provisioning = job && (job.state === 'queued' || job.state === 'running')
+    && /add|cloud:up/.test(job.action || '');
+  if (provisioning || orphans[n]) return { release: false };
+  return { release: true, uuid: head.uuid, vm: n, reason: `owning VM-${n} left the fleet` };
+}
+
+module.exports = { decideAutoReleaseGoneHead };

package/npm/fleet-reconcile.js

@@ -0,0 +1,36 @@
+'use strict';
+
+// npm/fleet-reconcile.js — pure reconciliation helpers for the fleet dashboard's
+// "unrostered VM" safety net (improve38). The dashboard lists running GCP
+// instances and surfaces any that aren't in the roster (provisioned out-of-band
+// — raw `gcloud`, or a `cloud:up` whose roster write failed). The gcloud I/O
+// lives in server.js (the untestable server shell); the pure parse + set
+// difference live here so they're unit-tested without invoking gcloud.
+
+// Parse `gcloud compute instances list --format='value(name)'` output into the
+// sorted, de-duped fleet VM numbers it names — instances whose name matches
+// `<prefix><n>`. Non-matching lines (other instances, blank lines, gcloud/SSH
+// warning noise) are ignored.
+function parseRunningFleetVms(stdout, prefix) {
+  const re = new RegExp(`^${String(prefix).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(\\d+)$`);
+  const ns = String(stdout || '')
+    .split('\n')
+    .map((line) => {
+      const m = line.trim().match(re);
+      return m ? Number(m[1]) : null;
+    })
+    .filter((n) => n != null);
+  return [...new Set(ns)].sort((a, b) => a - b);
+}
+
+// Set difference: the `running` VM numbers that are NOT already accounted for in
+// `shown` (the roster plus any provisioning/orphan numbers already rendered as a
+// card). Returns a sorted, de-duped array — the numbers that need an Adopt card.
+function computeUnrostered(running, shown) {
+  const accounted = new Set(shown);
+  return [...new Set(running)]
+    .filter((n) => !accounted.has(n))
+    .sort((a, b) => a - b);
+}
+
+module.exports = { parseRunningFleetVms, computeUnrostered };

package/npm/fleet-reset.js

@@ -0,0 +1,144 @@
+'use strict';
+// Pure bash-script builders for the fleet dashboard's RESET actions
+// (scripts/operator/fleet-dashboard/server.js requires this). String
+// construction only — no I/O, no gcloud/docker exec — so the reset *recipe*
+// (what the remote bash actually does) stays unit-testable in isolation
+// (npm/fleet-reset.test.js), exactly like launch-config.js / fleet-env.js.
+// The dispatch (gcloud ssh → docker exec → startJob) stays in server.js as
+// platform-glue; only the decision-bearing script shape lives here.
+
+// The `.codeyam` deep-clean preserve→pause→wipe→restore sequence, shared by every
+// reset that hard-cleans a /workspace. `git reset --hard` + `session-reset`
+// leave the git-IGNORED runtime state behind (workflow step files,
+// scenario-*.js, server-state, logs, caches), so we explicitly wipe and
+// restore the tracked `.codeyam`. Two gitignored files MUST survive the wipe:
+//   - editor.local.json — previewOrigin + the agent API key (a blind wipe
+//     breaks Live Preview + auth).
+//   - server-state.json — the running pid + control port the restart's verify
+//     reads.
+// Both are cp'd aside, `.codeyam` is wiped, restored from the branch (tracked,
+// e.g. self-host) or re-`init`'d (greenfield, where `.codeyam` is gitignored),
+// then the two files are copied back. Returned as step strings the caller
+// joins into its own `&&`-chain (the surrounding `( …; true )` guards keep each
+// best-effort cp from breaking the chain when a file is absent).
+//
+// First step: release any commit-queue entries this VM owns. The wipe
+// regenerates `.codeyam/run/queue-origin-id`, which would otherwise orphan
+// the prior session's entry (different origin_id, same machine — invisible
+// to the two-key adoption path until the next enqueue's same-machine guard
+// reaps it). Routing through `branch-queue release-mine` makes the
+// queue-side cleanup intentional and visible in the queue log instead.
+// Best-effort: a no-remote / queue-disabled project legitimately exits
+// non-zero, and we should not block the reset.
+//
+// Between the cp-asides and the `rm -rf` we cooperatively pause the editor
+// server (`stop-server --hold-for-restart`). Without that, the server keeps
+// writing to `.codeyam/logs/editor-server.log` and `.codeyam/run/` between
+// when `rm -rf` enumerates the dir and when it tries to `rmdir` the empty
+// directory — it surfaces as `rm: cannot remove '.codeyam': Directory not
+// empty`, which the dashboard reports as `error`. SIGUSR2 closes listeners +
+// stops the dev-server and parks the PID; the parent script's trailing
+// `restart-server --force-in-container` then resurrects via the existing
+// SIGUSR1 in-place reexec. Fail-soft `|| true` so a server that's already
+// dead (e.g. the reset is rerun after a partial failure) doesn't block the
+// chain.
+function codeyamDeepCleanSteps(E) {
+  return [
+    `( ${E} editor branch-queue release-mine --yes 2>/dev/null; true )`,
+    '( cp .codeyam/editor.local.json /tmp/cy-elj.bak 2>/dev/null; true )',
+    '( cp .codeyam/server-state.json /tmp/cy-ss.bak 2>/dev/null; true )',
+    `(${E} editor stop-server --hold-for-restart --force-in-container || true)`,
+    'rm -rf .codeyam',
+    `( git checkout HEAD -- .codeyam 2>/dev/null || ${E} init )`,
+    '( test -f /tmp/cy-elj.bak && mkdir -p .codeyam && cp /tmp/cy-elj.bak .codeyam/editor.local.json && rm -f /tmp/cy-elj.bak; true )',
+    '( test -f /tmp/cy-ss.bak && mkdir -p .codeyam && cp /tmp/cy-ss.bak .codeyam/server-state.json && rm -f /tmp/cy-ss.bak; true )',
+  ];
+}
+
+// Build the in-container bash for "Reset client" — hard-clean the CLIENT
+// project (/workspace) on ANY VM shape. The decisions encoded here:
+//   - Reset to HEAD, NOT origin: `git reset --hard` (bare) discards uncommitted
+//     churn but PRESERVES committed work. Advancing to origin tip is the
+//     separate "Update client" action — this must never `git fetch`/reset to
+//     `origin/<branch>`.
+//   - `git reset --hard` leaves untracked files, so node_modules + a per-VM
+//     .env survive (no forced re-install / lost secrets).
+//   - Stop the broker FIRST so abandoned agent WIP can't be re-written to disk
+//     mid-reset; drop a stale LOCAL credential.helper (fragility #29) so the
+//     re-seed + the agent's git ops fall back to the working system helper.
+//   - Re-seed the git credential cache AFTER the restart so the agent can
+//     pull/push immediately; the re-seed is a self-contained subshell whose
+//     own `|| echo` never masks an earlier &&-chain failure.
+// `E` is the in-container editor binary; `gitReseedBody` is the re-seed bash
+// body (passed in so this stays a pure function of its inputs).
+function resetClientScript({ E, gitReseedBody }) {
+  return [
+    'cd /workspace',
+    `command -v ${E} >/dev/null`,
+    'echo ">> [1/5] stopping agent session"',
+    `(${E} editor pty-broker stop || true)`,
+    '(git config --local --unset-all credential.helper || true)',
+    'echo ">> [2/5] discarding uncommitted changes (git reset --hard to HEAD; keeps committed work + untracked files)"',
+    'git reset --hard',
+    'echo ">> [3/5] deep-cleaning .codeyam (clears ignored runtime state; keeps editor.local.json + server-state.json)"',
+    ...codeyamDeepCleanSteps(E),
+    `${E} editor session-reset`,
+    'echo ">> [4/5] restarting server to respawn the broker (no rebuild)"',
+    `(${E} editor restart-server --force-in-container || true)`,
+    'echo ">> [5/5] re-seeding git credential cache"',
+    `( ( ${gitReseedBody} ) || echo "WARN git cache re-seed failed" )`,
+  ].join(' && ');
+}
+
+// Build the in-container bash for "Reset editor" — the editor-state recipe:
+// stop the agent, drop a stale local credential.helper, advance the VM's branch
+// to origin tip (skipped on a greenfield local-only repo), deep-clean .codeyam
+// (preserving editor.local.json + server-state.json via codeyamDeepCleanSteps),
+// run session-reset, and restart the server. This is the SAME &&-chain
+// previously inlined in actionResetEditorSource in scripts/operator/
+// fleet-dashboard/server.js — extracted so the standalone Reset editor action
+// AND the composite Update & Reset Everything action share one definition and
+// it gets unit-test coverage like the other reset builders.
+//
+// Binary-existence gate FIRST so a broken binary aborts BEFORE the destructive
+// `git reset --hard` / `rm -rf .codeyam`. The composite action relies on this
+// same gate as its safety contract — a failed rebuild that leaves no binary
+// will short-circuit the trailing recipe before any wipe happens.
+function resetEditorStateScript({ E }) {
+  return [
+    'cd /workspace',
+    `command -v ${E} >/dev/null`,
+    // Tolerate a missing broker: `pty-broker stop` exits non-zero when none is
+    // running; the subshell + `|| true` keeps it non-fatal without swallowing
+    // the binary-existence gate above.
+    'echo ">> [1/4] stopping agent session + clearing workflow state"',
+    `(${E} editor pty-broker stop || true)`,
+    // Drop a stale LOCAL credential.helper (fragility #29) so `git fetch` falls
+    // back to the working system helper. No-op when none is set.
+    '(git config --local --unset-all credential.helper || true)',
+    // Advance the VM's own branch to origin (skip on a greenfield local-only repo
+    // with no remote). fetch + `reset --hard origin/<branch>`, NOT `pull --ff-only`
+    // (which dies "Cannot fast-forward to multiple branches" on some VM states).
+    'if git remote | grep -qx origin; then ' +
+      'BR=$(git branch --show-current); ' +
+      'echo ">> [2/4] advancing source on $BR to origin tip"; ' +
+      'git reset --hard && git fetch origin "$BR" && git reset --hard "origin/$BR"; ' +
+    'else echo ">> [2/4] no origin remote (greenfield project) — skipping source advance"; fi',
+    // Deep-clean .codeyam: `git reset --hard` + session-reset leave git-IGNORED /
+    // untracked state (workflow + design-step state, server-state, logs, caches).
+    // Preserve editor.local.json (previewOrigin + agent API key — a blind wipe
+    // breaks Live Preview + auth) and server-state.json (runtime pid + control
+    // port the restart's verify reads), wipe .codeyam, restore it from the branch
+    // (tracked, e.g. self-host) or re-init (greenfield), then put both files back.
+    'echo ">> [3/4] deep-cleaning .codeyam (clears ignored state; keeps editor.local.json + server-state.json)"',
+    ...codeyamDeepCleanSteps(E),
+    `${E} editor session-reset`,
+    // No rebuild here (that's Rebuild binary). Restart the server in place to
+    // respawn the broker we stopped: restart-server SIGUSR1s pid 1 and the
+    // docker-exec returns cleanly, so `|| true` keeps a broker-down VM green.
+    'echo ">> [4/4] restarting server to respawn the broker (no rebuild)"',
+    `(${E} editor restart-server --force-in-container || true)`,
+  ].join(' && ');
+}
+
+module.exports = { codeyamDeepCleanSteps, resetClientScript, resetEditorStateScript };