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

package/npm/fleet-build-data.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// Assemble the per-VM wire object the dashboard's /data response carries to the
+// browser. This is the single source of truth for a card's transport shape: the
+// card UI (scripts/operator/fleet-dashboard/public/index.html) reads `v.<field>`
+// off each entry, so every field the card renders MUST be emitted here.
+//
+// It was split out of server.js's buildData() so the shape is unit-testable.
+// The regression that motivated the split: `currentProvider` (the VM's
+// configured build agent) was merged onto the poll state AND read by the card to
+// render the 🤖 agent badge, but it was silently missing from this envelope — so
+// it lived in server memory and never reached the browser, and the badge never
+// appeared. A hand-maintained object literal inside a 197KB monolith has no
+// guard against that drift; a pure function does.
+//
+// `v` is the merged poll state (state.vms[n]). `ctx` carries the derived,
+// cross-VM, and side-effecting values buildData computes per VM (status,
+// debounced broker tri-state, reconciled job, queue position, launch cfg, …) —
+// the things this pure function can't know on its own.
+function buildVmEnvelope(v, ctx) {
+  return {
+    n: ctx.n,
+    url: v.url || null,
+    reachable: !!v.reachable,
+    hasSession: !!v.hasSession,
+    // Three-state: true = broker confirmed up, false = confirmed down, null =
+    // editor unreachable so broker state is unknown. Never conflate "down" with
+    // "unreachable" — that mismatch is what made the card show "broker down"
+    // while a direct pgrep proved the broker was up.
+    brokerLive: v.reachable ? !!v.agentBrokerLive : null,
+    // Broker tri-state: 'down' | 'idle' | 'agent-live' | 'unknown' (derived
+    // upstream, debounced). Richer than brokerLive's is-an-agent-live boolean.
+    brokerStatus: ctx.brokerStatus,
+    awaitingInput: !!v.awaitingUserInput,
+    feature: v.feature || null,
+    step: v.step != null ? v.step : null,
+    mode: v.mode || null,
+    label: v.label || null,
+    status: ctx.status,
+    orphan: ctx.orphan || null,
+    degradedReasons: ctx.degradedReasons || [],
+    isHead: !!ctx.isHead,
+    // True when this VM holds the queue head but is unreachable (operator
+    // decides manually whether to release it).
+    headHolderUnreachable: !!ctx.headHolderUnreachable,
+    queuePos: ctx.queuePos != null ? ctx.queuePos : null,
+    queueLen: ctx.queueLen,
+    job: ctx.job || null,
+    config: ctx.config || null,
+    project: ctx.project != null ? ctx.project : null,
+    variant: ctx.variant != null ? ctx.variant : null,
+    cardIdentity: ctx.cardIdentity,
+    brokerHistory: Array.isArray(v.brokerHistory) ? v.brokerHistory : [],
+    brokerDeath: ctx.brokerDeath,
+    // Auth state + reason + token expiry. Only surfaced when the editor is
+    // reachable (an unreachable VM's cached auth is stale and misleading).
+    providerAuth: v.reachable && v.providerAuth ? v.providerAuth : null,
+    effects: v.effects || null,
+    // The VM's live-configured build agent (lowercase provider), reported by
+    // /api/session-info and merged (sticky) onto the poll state. Drives the
+    // card's 🤖 agent badge. null for an older VM whose editor predates the
+    // field (the card omits the badge rather than rendering a blank chip).
+    currentProvider: v.currentProvider || null,
+  };
+}
+
+// The fields the card UI depends on being present in every /data VM entry. This
+// is the contract `buildVmEnvelope` must satisfy: the regression that prompted
+// this module was a field the card read but the envelope didn't emit, so the
+// test asserts the envelope keys are a superset of this list. Adding a field the
+// card renders means adding it here AND in buildVmEnvelope — the test fails loud
+// if you do one without the other.
+const REQUIRED_CARD_FIELDS = [
+  'n', 'url', 'reachable', 'hasSession', 'brokerLive', 'brokerStatus',
+  'awaitingInput', 'feature', 'step', 'mode', 'label', 'status', 'orphan',
+  'degradedReasons', 'isHead', 'headHolderUnreachable', 'queuePos', 'queueLen',
+  'job', 'config', 'project', 'variant', 'cardIdentity', 'brokerHistory',
+  'brokerDeath', 'providerAuth', 'effects', 'currentProvider',
+];
+
+module.exports = { buildVmEnvelope, REQUIRED_CARD_FIELDS };

package/npm/fleet-cleanup.js

@@ -0,0 +1,297 @@
+'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 +
+// (for up adds) project-wiring verdict, returns a tag the caller dispatches on.
+//   verdict             when                                              dispatch
+//   'cleanup'           destroy gone, OR add gone                         runDestroyCleanup / runAddCleanup
+//   'reconcile-add'     add up, container up, project wired (or unknown)  ensure roster + recordLaunch, then clear
+//   'half-provisioned'  add up, container up, but project NOT wired       surface needs-recovery card (finish-wire from cfg)
+//   '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 distinguishes a finished add from a container-
+// down 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. The
+// `projectWired` axis closes the remaining gap (improve39 VM-7): an instance +
+// container that ARE up but whose `/workspace` is unwired (no git remote, empty
+// manifest) is NOT a finished add — it's half-provisioned and must surface a
+// recoverable card, not be silently reconciled "done". Only a POSITIVE unwired
+// signal (`projectWired === false`) downgrades to 'half-provisioned'; an
+// unknown/unprobed wiring (`null`/`undefined`) stays 'reconcile-add' so a flaky
+// probe can't strand a healthy VM. `containerUp`/`projectWired` are only consulted
+// for an add whose instance exists; destroy and the instance-gone add path ignore
+// them. Splitting the matrix out lets the table be exhaustively tested without any
+// of the side-effects in server.js.
+function reapVerdict({ action, exists, containerUp, projectWired }) {
+  if (exists === null) return 'leave';
+  if (action === 'destroy') return exists ? 'clear-only' : 'cleanup';
+  if (action === 'add') {
+    if (!exists) return 'cleanup';
+    if (!containerUp) return 'recover-bootstrap';
+    return projectWired === false ? 'half-provisioned' : 'reconcile-add';
+  }
+  return 'leave';
+}
+
+// Classify whether a VM's editor `/workspace` is actually wired to a client
+// project, from a best-effort probe of two signals: the git remote URL and
+// whether `package.json` carries a real `name`. Pure: server.js runs the SSH +
+// `docker exec` probe and hands the raw stdout/err here so the decision is
+// unit-testable without a live VM.
+//   - err present (ssh/docker blip, timeout)        → null  (unknown — do NOT
+//     strand a healthy VM on a flaky probe; reapVerdict treats null as wired)
+//   - a git remote OR a non-empty package.json name → true  (wired)
+//   - neither (empty / no-git workspace)            → false (half-provisioned —
+//     the VM-7 signature: `/workspace` with no remote and an empty manifest)
+// The probe emits the two signals separated by the `---CY---` sentinel so this
+// parser is independent of locale/line-ending noise in the ssh transport.
+function classifyProjectWiring({ stdout, err } = {}) {
+  if (err) return null;
+  const parts = String(stdout == null ? '' : stdout).split('---CY---').map((s) => s.trim());
+  const remote = parts[0] || '';
+  const nameCount = Number((parts[1] || '0').trim()) || 0;
+  if (remote || nameCount > 0) return true;
+  return false;
+}
+
+// Durable exit marker for a detached `add` provision (improve40). The add's
+// `cloud:up` shell is spawned in its OWN session (detached) so a dashboard
+// SIGKILL — the 2GB launchd hard cap, exactly the kill that aborted the VM-7
+// add mid-flight — no longer reaches it; the provision keeps running. When that
+// detached shell finally exits it writes `add-<n>.exit` (its trailing exit code
+// + an ISO timestamp) into PENDING_JOBS_DIR, alongside the `add-<n>.json`
+// sidecar. The marker is the GROUND-TRUTH completion signal the next boot reads
+// instead of inferring `in-flight → error` from the lost child: a marker means
+// "the provision finished while the dashboard was away," its code says whether
+// it finished OK. The name is derived here so the shell `trap` (server.js) and
+// the JS reader build the exact same path.
+function exitMarkerName(n) {
+  return `add-${n}.exit`;
+}
+
+// Parse an exit-marker file body into { exitCode, finishedAt }, or null when the
+// body is missing/blank/malformed. Format is two lines — the numeric exit code
+// then an ISO timestamp — written by the shell trap. A non-integer first line is
+// treated as no-marker (null) so a half-written / corrupt marker falls back to
+// the gcloud reconcile path rather than being read as a bogus exit code. Pure:
+// takes the text so it's unit-testable without touching disk.
+function parseExitMarker(text) {
+  if (text == null) return null;
+  const lines = String(text).split('\n').map((s) => s.trim()).filter(Boolean);
+  if (!lines.length) return null;
+  const code = Number(lines[0]);
+  if (!Number.isInteger(code)) return null;
+  return { exitCode: code, finishedAt: lines[1] || null };
+}
+
+// Read VM-n's exit marker from `dir`, or null when it's absent/unreadable/
+// malformed (the still-running and never-written cases both surface as null).
+function readExitMarker(dir, n) {
+  try { return parseExitMarker(fs.readFileSync(path.join(dir, exitMarkerName(n)), 'utf8')); }
+  catch { return null; }
+}
+
+// Remove a consumed exit marker; a missing file is the already-cleared path, not
+// an error (mirrors clearPendingJob).
+function clearExitMarker(dir, n) {
+  try { fs.unlinkSync(path.join(dir, exitMarkerName(n))); }
+  catch (_) { /* missing is fine */ }
+}
+
+// Decide how a snapshot-restored `add` should be re-attached after a dashboard
+// restart, BEFORE any gcloud probe. Pure: takes the durable signals the boot
+// path gathers — whether the exit marker exists, its recorded code, and whether
+// the detached provision child is still alive (recorded pid, `kill -0`).
+//   verdict       when                                          dispatch
+//   'done'        marker present, exit code 0                   roster + recordLaunch, clear sidecar/marker
+//   'error'       marker present, non-zero exit code            surface the real failure, clear sidecar/marker
+//   'running'     no marker yet, child still alive              RE-ATTACH: keep polling, do NOT mark error
+//   'reconcile'   child gone, no usable marker                  fall through to fc.reapVerdict (gcloud probe)
+// This is the durable fix's brain: a provision that survived the kill (still
+// running, or finished while we were away) is classified from GROUND TRUTH, so
+// it is never blanket-converted `in-flight → error` the way the snapshot-only
+// path did (the improve39 VM-7 false `add-failed`). Only when the child is gone
+// AND left no parseable marker do we fall back to inferring state from gcloud —
+// `reconcile` hands that exact (exists, containerUp, projectWired) decision to
+// fc.reapVerdict. A marker whose first line isn't an integer is treated as
+// absent (parseExitMarker → null) so a corrupt marker reconciles rather than
+// asserting a bogus code. The matrix is exhaustively tested without a live VM.
+function reattachVerdict({ markerPresent, exitCode, childAlive } = {}) {
+  if (markerPresent) {
+    // Guard the null/undefined coercion BEFORE Number() — `Number(null)` is 0,
+    // which would masquerade as a clean exit. A marker with no parseable code
+    // (half-written / corrupt) must reconcile, not assert success.
+    const code = exitCode == null ? NaN : Number(exitCode);
+    if (Number.isInteger(code)) return code === 0 ? 'done' : 'error';
+    return 'reconcile'; // marker present but no parseable code — let gcloud decide
+  }
+  if (childAlive) return 'running';
+  return 'reconcile';
+}
+
+// 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 };
+}
+
+// improve40 — select the orphaned `add` jobs that must be reconciled from the
+// VM's REAL provision state even though their per-job sidecar is GONE. The
+// durable re-attach path (sidecar + exit marker + recorded pid) cannot fire for
+// these — a restart left only the snapshot record — so the snapshot job's
+// stashed `config` is the sole cfg source and a live gcloud probe is the only
+// ground truth. Pure: takes the restored jobs map + the set of `<action>-<n>`
+// sidecar keys the sidecar reap already owns; returns the [{ n, cfg }] the boot
+// path hands to reconcileViaGcloud. A job is selected when ALL hold:
+//   - it is an `add`,
+//   - it is flagged `restartOrphaned` (restoreFromSnapshot downgraded a
+//     running add → error because the dashboard restarted before it finished —
+//     this is the ONLY error state we re-probe; an add that failed IN-PROCESS
+//     carries a plain terminal `error` with no flag and stays surfaced), AND
+//   - NO `add-<n>` sidecar exists (a sidecar means the sidecar reap already
+//     owns it — never double-reconcile).
+// `cfg` rides from the job's `config`; null when the snapshot never carried one
+// (older snapshot) — the caller still probes, but a roster reconcile then can't
+// recordLaunch, exactly mirroring the sidecar path's `meta.cfg`-absent case.
+function orphanedAddsToReconcile({ jobs, sidecarKeys } = {}) {
+  const sidecars = sidecarKeys instanceof Set ? sidecarKeys : new Set(sidecarKeys || []);
+  const src = (jobs && typeof jobs === 'object') ? jobs : {};
+  const out = [];
+  for (const [k, j] of Object.entries(src)) {
+    if (!j || typeof j !== 'object') continue;
+    if (j.action !== 'add') continue;
+    if (!j.restartOrphaned) continue;
+    if (sidecars.has(`add-${k}`)) continue;
+    out.push({ n: Number(k), cfg: j.config || null });
+  }
+  return out;
+}
+
+// improve41 — the destroy-direction mirror of orphanedAddsToReconcile: decide
+// what to do with a VM that is STILL in the roster but whose GCP instance state
+// we have just re-probed. The bug this closes: a Destroy that races a dashboard
+// restart can leave the instance deleted while the startup reap took the
+// `clear-only` path (instance still present at reap time) and dropped the only
+// sidecar — so nothing ever runs roster cleanup and the VM polls forever
+// "unreachable." A sidecar-independent reconcile, keyed on REAL GCP existence
+// rather than on a pending-job sidecar, catches it. Pure: server.js runs the
+// gcloud describe (→ exists, via classifyDescribeError) and reads session /
+// pending-add state, and hands the three facts here so the matrix is testable
+// without a live VM.
+//   verdict     when                                        dispatch
+//   'cleanup'   instance gone AND the VM is idle            runDestroyCleanup
+//   'leave'     exists uncertain (null), OR the VM is busy  do nothing this pass
+//   'keep'      instance still exists                       do nothing (healthy)
+// Fail-safe by construction: cleanup fires ONLY on a DEFINITIVE absence
+// (exists === false) — a flaky/transient describe (null) is always 'leave', so a
+// gcloud blip can never evict a healthy VM (mirroring reapVerdict's `leave`
+// posture). "Busy" (a live session or an in-flight add to this number) also
+// holds the entry for an operator rather than auto-removing — the shouldn't-
+// happen-but-fail-safe case where a vanished instance still reports a session.
+function reconcileRosteredVm({ exists, hasSession, hasPendingAdd } = {}) {
+  if (exists === null || exists === undefined) return "leave";
+  if (exists) return "keep";
+  if (hasSession || hasPendingAdd) return "leave";
+  return "cleanup";
+}
+
+module.exports = {
+  parsePendingJobFilename,
+  persistPendingJob,
+  clearPendingJob,
+  listPendingJobs,
+  classifyDescribeError,
+  reapVerdict,
+  reconcileRosteredVm,
+  orphanedAddsToReconcile,
+  classifyProjectWiring,
+  recoverBootstrapDecision,
+  exitMarkerName,
+  parseExitMarker,
+  readExitMarker,
+  clearExitMarker,
+  reattachVerdict,
+};

package/npm/fleet-effect-status.js

@@ -0,0 +1,179 @@
+'use strict';
+// Pure predicate module for the Fleet Dashboard's per-button "will clicking
+// this change the VM, or is it already in that state?" indicators
+// (scripts/operator/fleet-dashboard/server.js requires this). Given an
+// already-gathered FACTS object — no I/O, no git/docker exec; server.js does
+// the impure fact-gathering — computeButtonEffects returns a per-button verdict
+// map. Mirrors the pure-module-plus-colocated-vitest-test shape of
+// npm/fleet-reset.js so the whole decision table is unit-testable without
+// spawning a process.
+//
+// Each verdict is { effect, reason }:
+//   - 'changes'     — clicking does something; `reason` says what.
+//   - 'noop'        — already in that state; clicking changes nothing.
+//   - 'recommended' — soft signal (run-setup only): a reset/update landed after
+//                     the last successful setup. NEVER a confident green no-op.
+//   - 'unknown'     — not yet checked, VM unreachable, or a needed fact is
+//                     missing. We never CLAIM a safe no-op we couldn't verify —
+//                     silent failure here would be worse than no indicator.
+//
+// The predicate for each button is derived from what that button actually
+// touches (its tooltip in public/index.html is the source of truth): the sync
+// buttons key off a git commit comparison, the reset buttons off
+// working-tree/session/`.codeyam` state, and rebuild off a build-commit
+// comparison.
+
+// Short sha for compact reason strings. Tolerates null / short input.
+function short(sha) {
+  return sha ? String(sha).slice(0, 7) : '?';
+}
+
+// "origin/<branch>" — or a bare "origin" when the branch is unknown.
+function originRef(branch) {
+  return branch ? `origin/${branch}` : 'origin';
+}
+
+// "N commit(s) behind origin/<branch>" with correct singular/plural.
+function behindReason(behind, branch) {
+  return `${behind} commit${behind === 1 ? '' : 's'} behind ${originRef(branch)}`;
+}
+
+// Compose a short reason listing which signals make a reset non-trivial, so the
+// operator sees WHAT a Reset would discard rather than a bare "changes". The
+// `agent` (a live build agent in the broker) leads the list — it's the most
+// consequential thing a reset's `pty-broker stop` would silently discard.
+function resetReason({ agent, session, dirty, behind, codeyam }) {
+  const parts = [];
+  if (agent) parts.push('running build agent');
+  if (dirty) parts.push('uncommitted changes');
+  if (behind) parts.push('source behind origin');
+  if (session) parts.push('active session');
+  if (codeyam) parts.push('.codeyam state');
+  return parts.length ? `will discard: ${parts.join(', ')}` : 'will reset state';
+}
+
+// The action ids governed by an effect indicator — the same ids server.js /
+// index.html use for the buttons. Reconfigure / Env / Destroy are deliberately
+// absent (one-shots, not converge-to-a-state actions, so a no-op predicate is
+// meaningless for them).
+const ACTION_IDS = [
+  'update-client-source',
+  'update-editor-source',
+  'reset-editor-source',
+  'reset-client',
+  'rebuild-binary',
+  'update-reset-everything',
+  'run-setup',
+];
+
+// facts (a plain object gathered by server.js — no I/O):
+//   {
+//     reachable: boolean,
+//     hasSession: boolean,
+//     client:  { headSha, originSha, behind, dirty } | null,     // /workspace
+//     editor:  { headSha, originSha, behind, dirty, buildCommit } | null,
+//     codeyamDirty: boolean,
+//     setupRanSince: boolean,        // a setup completed after the last reset/update
+//     clientBranch: string | null,   // for reason text only
+//     editorBranch: string | null,   // for reason text only
+//   }
+function computeButtonEffects(facts) {
+  const f = facts || {};
+
+  // Unreachable VM (or no facts at all): every governed button is unknown. We
+  // could not reach the editor to gather facts, so never render a green no-op.
+  if (!f.reachable) {
+    const out = {};
+    for (const id of ACTION_IDS) out[id] = { effect: 'unknown', reason: 'VM unreachable' };
+    return out;
+  }
+
+  const client = f.client || null;
+  const editor = f.editor || null;
+  const hasSession = !!f.hasSession;
+  const codeyamDirty = !!f.codeyamDirty;
+  // A live build agent in the broker. A reset's first step is `pty-broker stop`,
+  // which kills it regardless of whether a workflow session is registered — so
+  // this is discardable work even when hasSession is false. Explicit-true only:
+  // a null/absent value (older or unreachable VM) must NOT flip a genuine noop.
+  const brokerLive = f.brokerLive === true;
+
+  // (1) Update client — ff-advance /workspace to origin tip. Changes iff behind.
+  const updateClient = client == null
+    ? { effect: 'unknown', reason: 'client state not checked' }
+    : client.behind > 0
+      ? { effect: 'changes', reason: behindReason(client.behind, f.clientBranch) }
+      : { effect: 'noop', reason: 'up to date with ' + originRef(f.clientBranch) };
+
+  // (2) Update editor — advance the editor source the binary builds from.
+  const updateEditor = editor == null
+    ? { effect: 'unknown', reason: 'editor state not checked' }
+    : editor.behind > 0
+      ? { effect: 'changes', reason: behindReason(editor.behind, f.editorBranch) }
+      : { effect: 'noop', reason: 'up to date with ' + originRef(f.editorBranch) };
+
+  // (5) Rebuild binary — advances source then compiles. Changes iff the running
+  // binary's build commit differs from the editor origin tip. Unknown when we
+  // don't have both commits to compare.
+  const rebuild = (editor == null || !editor.buildCommit || !editor.originSha)
+    ? { effect: 'unknown', reason: 'binary/source commit not checked' }
+    : editor.buildCommit !== editor.originSha
+      ? { effect: 'changes', reason: `binary at ${short(editor.buildCommit)}, ${originRef(f.editorBranch)} at ${short(editor.originSha)}` }
+      : { effect: 'noop', reason: 'binary built from ' + originRef(f.editorBranch) + ' tip' };
+
+  // (3) Reset editor — discards uncommitted + session, advances source, wipes
+  // .codeyam. No-op ONLY when clean at origin tip with no session.
+  const resetEditor = editor == null
+    ? { effect: 'unknown', reason: 'editor state not checked' }
+    : (brokerLive || hasSession || editor.dirty || editor.behind > 0 || codeyamDirty)
+      ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: editor.dirty, behind: editor.behind > 0, codeyam: codeyamDirty }) }
+      : { effect: 'noop', reason: 'already clean at origin tip, no session' };
+
+  // (3b) Reset client — hard-clean /workspace + .codeyam, drop the session.
+  // No source-advance, so `behind` is NOT part of this predicate.
+  const resetClient = client == null
+    ? { effect: 'unknown', reason: 'client state not checked' }
+    : (brokerLive || client.dirty || codeyamDirty || hasSession)
+      ? { effect: 'changes', reason: resetReason({ agent: brokerLive, session: hasSession, dirty: client.dirty, behind: false, codeyam: codeyamDirty }) }
+      : { effect: 'noop', reason: 'already clean, no session' };
+
+  // (4b) Update & Reset Everything — composite. Changes iff ANY component would
+  // change: rebuild-binary, reset-editor-source, or the client being
+  // behind/dirty. Reason summarizes which parts.
+  const everything = (() => {
+    if (editor == null || client == null) {
+      return { effect: 'unknown', reason: 'state not checked' };
+    }
+    const parts = [];
+    if (rebuild.effect === 'changes') parts.push('rebuild');
+    if (resetEditor.effect === 'changes') parts.push('reset editor');
+    if (client.behind > 0 || client.dirty) parts.push('reset client');
+    if (parts.length > 0) return { effect: 'changes', reason: parts.join(' + ') };
+    // No part would change. But if a component was itself unverifiable, don't
+    // claim a confident no-op — fall back to unknown.
+    if (rebuild.effect === 'unknown' || resetEditor.effect === 'unknown') {
+      return { effect: 'unknown', reason: 'state not checked' };
+    }
+    return { effect: 'noop', reason: 'everything already at origin tip, no session' };
+  })();
+
+  // (run-setup) Honest soft signal — there is no cheap upstream proof that
+  // `npm run setup` would change nothing (DB/migration state isn't
+  // introspected). `recommended` when a reset/update landed after the last
+  // successful setup; otherwise `unknown`. Never a confident green no-op.
+  const runSetup = f.setupRanSince
+    ? { effect: 'unknown', reason: 'no setup-affecting change since last setup' }
+    : { effect: 'recommended', reason: 'a reset/update landed since the last setup' };
+
+  return {
+    'update-client-source': updateClient,
+    'update-editor-source': updateEditor,
+    'reset-editor-source': resetEditor,
+    'reset-client': resetClient,
+    'rebuild-binary': rebuild,
+    'update-reset-everything': everything,
+    'run-setup': runSetup,
+  };
+}
+
+module.exports = { computeButtonEffects, ACTION_IDS };