rollbridge 0.1.5 → 0.1.6

package/src/daemon.js

@@ -4,13 +4,19 @@ import fs from "node:fs/promises"
 import http from "node:http"
 import net from "node:net"
 import httpProxy from "http-proxy"
+import EventLog from "./event-log.js"
 import ReleaseGroup from "./release-group.js"
+import {clearState, isProcessAlive, liveProcesses, readState, writeState} from "./state-store.js"
+import {resolveGroupId, resolveUserId} from "./system-ids.js"
+
+const EVENT_HISTORY_LIMIT = 1000
+const STATE_PERSIST_INTERVAL_MS = 5000
 
 /**
  * @typedef {import("./json.js").JsonValue} JsonValue
  * @typedef {{releaseId?: string, releasePath: string, revision?: string}} DeployArgs
  * @typedef {{id: string, process: import("./managed-process.js").ManagedProcessStatus}} ProcessStatus
- * @typedef {{activeReleaseId: string | null, application: string, control: import("./config.js").ControlConfig, proxy: {host: string, port: number | undefined, upstreamHost: string}, releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
+ * @typedef {{activeReleaseId: string | null, application: string, control: import("./config.js").ControlConfig, orphans: {id: string, pid: number, releaseId: string | null}[], proxy: {host: string, port: number | undefined, upstreamHost: string}, releases: import("./release-group.js").ReleaseStatus[], services: ProcessStatus[], singletons: ProcessStatus[]}} DaemonStatus
  */
 
 export default class RollbridgeDaemon {
@@ -21,7 +27,18 @@ export default class RollbridgeDaemon {
    */
   constructor({config, logger}) {
     this.config = config
-    this.logger = logger || ((message, data = {}) => console.log(JSON.stringify({at: new Date().toISOString(), data, message})))
+    this.eventLog = new EventLog(EVENT_HISTORY_LIMIT)
+
+    const baseLogger = logger || ((message, data = {}) => console.log(JSON.stringify({at: new Date().toISOString(), data, message})))
+
+    // Every operational milestone is logged through this.logger, so recording here
+    // gives a structured event history for free (deploys, switches, stops, crashes,
+    // restarts, and failed commands).
+    this.logger = /** @type {(message: string, data?: Record<string, JsonValue>) => void} */ ((message, data = {}) => {
+      this.eventLog.record(message, data)
+      baseLogger(message, data)
+    })
+
     this.releases = /** @type {Map<string, ReleaseGroup>} */ (new Map())
     this.services = /** @type {Map<string, import("./managed-process.js").default>} */ (new Map())
     this.servicePorts = /** @type {Record<string, number>} */ ({})
@@ -32,14 +49,22 @@ export default class RollbridgeDaemon {
     this.controlServer = /** @type {net.Server | undefined} */ (undefined)
     this.proxyPort = /** @type {number | undefined} */ (undefined)
     this.stopping = false
+    this.statePath = config.statePath
+    this.persistTimer = /** @type {ReturnType<typeof setInterval> | undefined} */ (undefined)
+    this.pendingWrite = /** @type {Promise<void> | undefined} */ (undefined)
+    // Still-alive managed processes left by a previous daemon (from statePath), captured at
+    // startup and surfaced in status(). The daemon cannot re-manage them, only report them.
+    this.orphans = /** @type {{id: string, pid: number, releaseId: string | null}[]} */ ([])
 
     this.proxy.on("error", (error, req, res) => this.onProxyError(error, req, res))
   }
 
   /** @returns {Promise<void>} Starts proxy and control listeners. */
   async start() {
+    await this.reportOrphans()
     await this.startProxy()
     await this.startControlServer()
+    this.startStatePersistence()
   }
 
   /** @returns {Promise<void>} Starts the stable local proxy. */
@@ -78,6 +103,30 @@ export default class RollbridgeDaemon {
     if (this.config.control.mode !== undefined) {
       await fs.chmod(this.config.control.path, this.config.control.mode)
     }
+
+    await this.applyControlSocketOwnership()
+  }
+
+  /**
+   * Applies control.owner/control.group to the bound socket via chown, resolving names to ids.
+   * @returns {Promise<void>} Resolves once ownership is applied (no-op when neither is set).
+   */
+  async applyControlSocketOwnership() {
+    const {group, owner, path: socketPath} = this.config.control
+
+    if (owner === undefined && group === undefined) return
+
+    // -1 leaves the uid/gid unchanged (POSIX chown semantics).
+    const uid = owner === undefined ? -1 : resolveUserId(owner)
+    const gid = group === undefined ? -1 : resolveGroupId(group)
+
+    try {
+      await fs.chown(socketPath, uid, gid)
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error)
+
+      throw new Error(`Could not set control socket owner/group on ${socketPath}: ${reason}. Run the daemon as a user allowed to chown it (for example root, or a member of the target group).`, {cause: error})
+    }
   }
 
   /** @returns {Promise<void>} Removes a stale Unix socket before binding, or fails clearly when a daemon is alive. */
@@ -195,6 +244,7 @@ export default class RollbridgeDaemon {
     this.executeControlLine(line)
       .then((response) => socket.write(`${JSON.stringify({status: "success", ...response})}\n`))
       .catch((error) => {
+        this.logger("command failed", {error: error instanceof Error ? error.message : String(error)})
         socket.write(`${JSON.stringify({
           error: error instanceof Error ? error.message : String(error),
           status: "error"
@@ -228,6 +278,10 @@ export default class RollbridgeDaemon {
       return this.status()
     }
 
+    if (commandName === "events") {
+      return {events: this.eventLog.recent(typeof data.limit === "number" ? data.limit : undefined)}
+    }
+
     if (commandName === "stop") {
       await this.stopRelease(stringOrUndefined(data.releaseId))
       return this.status()
@@ -240,6 +294,10 @@ export default class RollbridgeDaemon {
       })
     }
 
+    if (commandName === "rollback") {
+      return await this.rollback({releaseId: stringOrUndefined(data.releaseId)})
+    }
+
     if (commandName === "shutdown") {
       setImmediate(() => {
         this.shutdown().catch((error) => {
@@ -278,6 +336,7 @@ export default class RollbridgeDaemon {
       await this.ensureServices(release, startedServices)
       await release.start()
     } catch (error) {
+      this.logger("deploy failed", {error: error instanceof Error ? error.message : String(error), releaseId: newReleaseId})
       await this.stopStartedServices(startedServices)
       throw error
     }
@@ -296,12 +355,60 @@ export default class RollbridgeDaemon {
       void this.drainAndPrune(previousRelease)
     }
 
+    this.persistState()
+
     return {
       activeReleaseId: release.releaseId,
       previousReleaseId: previousRelease ? previousRelease.releaseId : null
     }
   }
 
+  /**
+   * Rolls back to a previously-active release by re-running the deploy flow on its
+   * retained metadata: it re-starts the target release, health-checks it, switches
+   * traffic, replaces singletons, and drains the current release — just like a deploy,
+   * so a failed rollback leaves the current release active.
+   * @param {{releaseId?: string}} [args] - Target release id; defaults to the most recently retired release.
+   * @returns {Promise<Record<string, JsonValue>>} The rollback result.
+   */
+  async rollback({releaseId} = {}) {
+    const target = releaseId ? this.releases.get(releaseId) : this.previousRelease()
+
+    if (!target) {
+      throw new Error(releaseId ? `No retained release "${releaseId}" to roll back to.` : "No previous release to roll back to.")
+    }
+
+    if (target === this.activeRelease) {
+      throw new Error(`Release "${target.releaseId}" is already active.`)
+    }
+
+    // The target may still be draining a prior deploy (live processes). Stop it before the
+    // deploy below re-uses its id in this.releases, otherwise the still-running instance
+    // would be dropped from status/pruning/shutdown and could be orphaned.
+    if (target.state !== "stopped" && target.state !== "failed") {
+      await target.stop()
+    }
+
+    this.logger("rollback starting", {releaseId: target.releaseId, releasePath: target.releasePath})
+
+    return await this.deploy({releaseId: target.releaseId, releasePath: target.releasePath, revision: target.revision})
+  }
+
+  /**
+   * @returns {ReleaseGroup | undefined} The most recently active release other than the current one, if any.
+   */
+  previousRelease() {
+    /** @type {ReleaseGroup | undefined} */
+    let previous
+
+    for (const release of this.releases.values()) {
+      if (release === this.activeRelease || !release.activatedAt) continue
+      if (!previous || Date.parse(release.activatedAt) >= Date.parse(/** @type {string} */ (previous.activatedAt))) previous = release
+    }
+
+    return previous
+  }
+
   /**
    * Starts missing daemon-wide services before release-owned processes need them.
    * @param {ReleaseGroup} release - Release providing templates and ports.
@@ -324,7 +431,7 @@ export default class RollbridgeDaemon {
       }
 
       try {
-        await service.start()
+        await service.start("deploy")
         startedServices.push(processConfig.id)
       } catch (error) {
         this.services.delete(processConfig.id)
@@ -370,11 +477,14 @@ export default class RollbridgeDaemon {
         command: nextDefinition.command,
         cwd: nextDefinition.cwd,
         env: nextDefinition.env,
+        lifecycle: nextDefinition.lifecycle,
         logger: nextDefinition.logger,
+        memory: nextDefinition.memory,
         outputLines: nextDefinition.outputLines,
         restart: nextDefinition.restart,
         restartDelayMs: nextDefinition.restartDelayMs,
         shouldRestart: nextDefinition.shouldRestart,
+        stopSignal: nextDefinition.stopSignal,
         stopTimeoutMs: nextDefinition.stopTimeoutMs
       })
     }
@@ -398,7 +508,7 @@ export default class RollbridgeDaemon {
       const singleton = release.buildProcess(processConfig)
 
       this.singletons.set(processConfig.id, singleton)
-      await singleton.start()
+      await singleton.start("deploy")
     }
   }
 
@@ -426,7 +536,7 @@ export default class RollbridgeDaemon {
     for (const target of targets) {
       this.logger("process restart requested", {processId: target.id})
       await target.process.stop()
-      await target.process.start()
+      await target.process.start("manual")
     }
 
     return {restarted: targets.map((target) => target.id)}
@@ -441,12 +551,14 @@ export default class RollbridgeDaemon {
 
     for (const processConfig of this.config.processes) {
       if (processConfig.policy === "proxied") continue
-      if (processId !== undefined && processConfig.id !== processId) continue
       if (policy !== undefined && processConfig.policy !== policy) continue
 
-      const process = this.findProcessInstance(processConfig)
+      for (const instance of this.runningInstances(processConfig)) {
+        // A processId selector matches the base config id (all replicas) or one replica's id.
+        if (processId !== undefined && processId !== processConfig.id && processId !== instance.id) continue
 
-      if (process) targets.push({id: processConfig.id, process})
+        targets.push(instance)
+      }
     }
 
     return targets
@@ -454,13 +566,22 @@ export default class RollbridgeDaemon {
 
   /**
    * @param {import("./config.js").ProcessConfig} processConfig - Process definition.
-   * @returns {import("./managed-process.js").default | undefined} The running instance, if any.
+   * @returns {{id: string, process: import("./managed-process.js").default}[]} Running instances (replicas) for this config.
    */
-  findProcessInstance(processConfig) {
-    if (processConfig.policy === "service") return this.services.get(processConfig.id)
-    if (processConfig.policy === "singleton") return this.singletons.get(processConfig.id)
+  runningInstances(processConfig) {
+    if (processConfig.policy === "service") {
+      const service = this.services.get(processConfig.id)
+
+      return service ? [{id: processConfig.id, process: service}] : []
+    }
 
-    return this.activeRelease ? this.activeRelease.getProcess(processConfig.id) : undefined
+    if (processConfig.policy === "singleton") {
+      const singleton = this.singletons.get(processConfig.id)
+
+      return singleton ? [{id: processConfig.id, process: singleton}] : []
+    }
+
+    return this.activeRelease ? this.activeRelease.getProcesses(processConfig.id) : []
   }
 
   /**
@@ -482,7 +603,9 @@ export default class RollbridgeDaemon {
     if (release === this.activeRelease) this.activeRelease = undefined
 
     await release.stop()
+    this.logger("release stopped", {releaseId: release.releaseId})
     this.pruneStoppedReleases()
+    this.persistState()
   }
 
   /**
@@ -493,10 +616,12 @@ export default class RollbridgeDaemon {
   async drainAndPrune(release) {
     try {
       await release.drainAndStop(this.config.proxy.drainTimeoutMs)
+      this.logger("release drained", {releaseId: release.releaseId})
     } catch (error) {
       this.logger("release drain failed", {error: error instanceof Error ? error.message : String(error), releaseId: release.releaseId})
     } finally {
       this.pruneStoppedReleases()
+      this.persistState()
     }
   }
 
@@ -509,11 +634,75 @@ export default class RollbridgeDaemon {
     }
   }
 
+  /** @returns {void} Starts periodic state persistence when statePath is configured. */
+  startStatePersistence() {
+    if (!this.statePath) return
+
+    this.persistState()
+    this.persistTimer = setInterval(() => this.persistState(), STATE_PERSIST_INTERVAL_MS)
+    this.persistTimer.unref?.()
+  }
+
+  /**
+   * Persists a state snapshot (status plus recent events) to statePath, atomically and
+   * fire-and-forget. A failed write is logged but never blocks daemon operation.
+   * @returns {void}
+   */
+  persistState() {
+    if (!this.statePath || this.stopping) return
+
+    const statePath = this.statePath
+    // Drop the orphans view from the snapshot: it reflects a *previous* daemon's leftovers, not
+    // this daemon's own managed state, and is recomputed from the persisted processes on restart.
+    const {orphans: _orphans, ...status} = this.status()
+    const snapshot = {...status, events: this.eventLog.recent(), persistedAt: new Date().toISOString()}
+
+    // Serialize writes (and track the tail) so shutdown can wait for an in-flight write before
+    // clearing the file — otherwise a write started before shutdown could recreate it afterward.
+    this.pendingWrite = Promise.resolve(this.pendingWrite)
+      .catch(() => {})
+      .then(() => writeState(statePath, snapshot))
+      .catch((error) => {
+        this.logger("state persist failed", {error: error instanceof Error ? error.message : String(error)})
+      })
+  }
+
+  /**
+   * On startup, reads any state left by a previous daemon and reports managed processes whose
+   * pids are still alive — likely orphans from a daemon that did not shut down cleanly. This is
+   * advisory (Rollbridge cannot re-adopt detached children); the operator stops the leftovers.
+   * A recycled pid could be a false positive, so reports are a prompt to investigate.
+   * @returns {Promise<void>} Resolves once orphans are reported.
+   */
+  async reportOrphans() {
+    if (!this.statePath) return
+
+    const orphans = liveProcesses(await readState(this.statePath))
+
+    // Keep them for status() so `rollbridge status` reflects still-running children after a
+    // restart, not just the startup log below.
+    this.orphans = orphans
+
+    for (const orphan of orphans) {
+      this.logger("orphaned managed process detected", {pid: orphan.pid, processId: orphan.id, releaseId: orphan.releaseId})
+    }
+
+    if (orphans.length > 0) {
+      this.logger("orphaned processes from a previous daemon", {count: orphans.length, hint: "a previous daemon did not shut down cleanly; verify these pids and stop any leftovers"})
+    }
+  }
+
   /** @returns {Promise<void>} Stops proxy, control socket, and child processes. */
   async shutdown() {
     if (this.stopping) return
 
     this.stopping = true
+
+    if (this.persistTimer) {
+      clearInterval(this.persistTimer)
+      this.persistTimer = undefined
+    }
+
     this.proxy.close()
     await Promise.allSettled([...this.services.values()].map((processInstance) => processInstance.stop()))
     await Promise.allSettled([...this.singletons.values()].map((processInstance) => processInstance.stop()))
@@ -521,6 +710,14 @@ export default class RollbridgeDaemon {
     await this.closeServer(this.proxyServer)
     await this.closeServer(this.controlServer)
     await fs.rm(this.config.control.path, {force: true})
+
+    // A clean shutdown leaves no orphans, so remove the state file rather than leaving stale
+    // pids. Wait for any in-flight write first so it can't recreate the file afterward (no new
+    // writes start: stopping is set and the persist timer is cleared above).
+    if (this.statePath) {
+      if (this.pendingWrite) await this.pendingWrite
+      await clearState(this.statePath)
+    }
   }
 
   /**
@@ -540,10 +737,16 @@ export default class RollbridgeDaemon {
 
   /** @returns {DaemonStatus} Status payload. */
   status() {
+    // Re-check liveness and prune the dead permanently, so the list self-clears as the operator
+    // stops the leftovers (e.g. via `rollbridge recover`). Pruning (not just filtering) matters:
+    // a cleared orphan must not reappear if the OS later recycles its pid for an unrelated process.
+    this.orphans = this.orphans.filter((orphan) => isProcessAlive(orphan.pid))
+
     return {
       activeReleaseId: this.activeRelease ? this.activeRelease.releaseId : null,
       application: this.config.application,
       control: {...this.config.control},
+      orphans: [...this.orphans],
       proxy: {
         host: this.config.proxy.host,
         port: this.proxyPort ?? this.config.proxy.port,

package/src/doctor.js

@@ -5,9 +5,12 @@ import fs from "node:fs/promises"
 import net from "node:net"
 import path from "node:path"
 import {inspectControlSocket} from "./daemon.js"
+import {liveProcesses, readState} from "./state-store.js"
+import {processTemplateContext, renderObject, renderTemplate} from "./template.js"
 
 /**
  * @typedef {{detail: string, name: string, ok: boolean}} DoctorCheck
+ * @typedef {{cwd: string, id: string, ok: true} | {error: string, id: string, ok: false}} ProcessRender
  */
 
 /**
@@ -25,9 +28,55 @@ export async function runEnvironmentChecks(config) {
   checks.push(await controlSocketDirectoryCheck(config))
   checks.push(await proxyPortCheck(config))
 
+  if (config.statePath !== undefined) {
+    // A live daemon persists its own (live) pids into the state file, so they are not orphans.
+    const daemonRunning = !("error" in socketInspection) && socketInspection.alive
+
+    checks.push(await statePathDirectoryCheck(config.statePath))
+    checks.push(await orphanCheck(config.statePath, daemonRunning))
+  }
+
   return checks
 }
 
+/**
+ * @param {string} statePath - Configured state file path.
+ * @returns {Promise<DoctorCheck>} Whether the state file's directory is writable.
+ */
+async function statePathDirectoryCheck(statePath) {
+  const directory = path.dirname(path.resolve(statePath))
+
+  try {
+    await fs.access(directory, fsConstants.W_OK | fsConstants.X_OK)
+
+    return {detail: `${directory} is writable`, name: "state path directory", ok: true}
+  } catch {
+    return {detail: `${directory} is missing or not writable; state cannot be persisted`, name: "state path directory", ok: false}
+  }
+}
+
+/**
+ * @param {string} statePath - Configured state file path.
+ * @param {boolean} daemonRunning - Whether a Rollbridge daemon is currently live on the control socket.
+ * @returns {Promise<DoctorCheck>} Whether any orphaned managed processes from a prior daemon are still alive.
+ */
+async function orphanCheck(statePath, daemonRunning) {
+  if (daemonRunning) {
+    // The running daemon owns the pids in the state file; they are managed, not orphaned.
+    return {detail: "a daemon is running; its managed processes are not orphans", name: "orphaned processes", ok: true}
+  }
+
+  const orphans = liveProcesses(await readState(statePath))
+
+  if (orphans.length === 0) {
+    return {detail: "no leftover processes from a previous daemon", name: "orphaned processes", ok: true}
+  }
+
+  const summary = orphans.map((orphan) => `${orphan.id} (pid ${orphan.pid})`).join(", ")
+
+  return {detail: `${orphans.length} possible orphaned process${orphans.length === 1 ? "" : "es"} still running: ${summary} — verify and stop any leftovers`, name: "orphaned processes", ok: false}
+}
+
 /**
  * @param {string} socketPath - Control socket path.
  * @returns {Promise<{alive: boolean, application?: string} | {error: string}>} Probe result, or the probe error.
@@ -112,3 +161,131 @@ async function canBindPort(host, port) {
     server.listen(port, host, () => server.close(() => resolve({ok: true})))
   })
 }
+
+/**
+ * Runs deploy-time checks against a specific release: that the release directory exists, that
+ * every process's command/cwd/env templates resolve, and that each rendered working directory
+ * exists. These need the per-release values that only exist at deploy time, so the operator
+ * supplies them (the release path, and optionally an id/revision). Ports referenced by templates
+ * are rendered with the low end of each process's configured range as a representative value.
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @param {{releaseId?: string, releasePath: string, revision?: string}} release - Release to render against.
+ * @returns {Promise<DoctorCheck[]>} One check per probed aspect.
+ */
+export async function runReleaseChecks(config, release) {
+  const releasePath = path.resolve(release.releasePath)
+  const releaseId = release.releaseId || release.revision || path.basename(releasePath)
+  const revision = release.revision || releaseId
+  const ports = representativePorts(config)
+  const renders = config.processes.map((processConfig) => renderProcess(processConfig, {application: config.application, ports, proxy: config.proxy, releaseId, releasePath, revision}))
+
+  return [await releasePathCheck(releasePath), templateCheck(renders), await workingDirectoryCheck(renders)]
+}
+
+/**
+ * @param {import("./config.js").RollbridgeConfig} config - Normalized config.
+ * @returns {Record<string, number>} The ports a deploy would allocate, using each range's low end.
+ */
+function representativePorts(config) {
+  /** @type {Record<string, number>} */
+  const ports = {}
+
+  for (const processConfig of config.processes) {
+    if (processConfig.port) ports[processConfig.id] = processConfig.port.from
+  }
+
+  return ports
+}
+
+/**
+ * Renders a process's command, cwd, and env against a deploy-time context (replica index 0).
+ * @param {import("./config.js").ProcessConfig} processConfig - Process to render.
+ * @param {{application: string, ports: Record<string, number>, proxy: import("./config.js").ProxyConfig, releaseId: string, releasePath: string, revision: string}} shared - Shared render inputs.
+ * @returns {ProcessRender} The rendered cwd, or the first template error.
+ */
+function renderProcess(processConfig, shared) {
+  const context = processTemplateContext({
+    application: shared.application,
+    ports: shared.ports,
+    processId: processConfig.id,
+    proxy: shared.proxy,
+    releaseId: shared.releaseId,
+    releasePath: shared.releasePath,
+    replicaCount: processConfig.replicas,
+    replicaIndex: 0,
+    revision: shared.revision
+  })
+
+  try {
+    const cwd = processConfig.cwd ? renderTemplate(processConfig.cwd, context) : shared.releasePath
+
+    renderTemplate(processConfig.command, context)
+    renderObject(processConfig.env, context)
+
+    return {cwd: path.resolve(shared.releasePath, cwd), id: processConfig.id, ok: true}
+  } catch (error) {
+    return {error: error instanceof Error ? error.message : String(error), id: processConfig.id, ok: false}
+  }
+}
+
+/**
+ * @param {string} releasePath - Resolved release directory.
+ * @returns {Promise<DoctorCheck>} Whether the release directory exists.
+ */
+async function releasePathCheck(releasePath) {
+  if (await isDirectory(releasePath)) {
+    return {detail: `${releasePath} exists`, name: "release path", ok: true}
+  }
+
+  return {detail: `${releasePath} is missing or not a directory`, name: "release path", ok: false}
+}
+
+/**
+ * @param {ProcessRender[]} renders - Per-process render results.
+ * @returns {DoctorCheck} Whether every process's templates resolved against the release context.
+ */
+function templateCheck(renders) {
+  const failures = renders.flatMap((render) => (render.ok ? [] : [`${render.id}: ${render.error}`]))
+
+  if (failures.length === 0) {
+    return {detail: `all ${renders.length} process command/cwd/env templates resolve`, name: "process templates", ok: true}
+  }
+
+  return {detail: `unresolved templates — ${failures.join("; ")}`, name: "process templates", ok: false}
+}
+
+/**
+ * @param {ProcessRender[]} renders - Per-process render results.
+ * @returns {Promise<DoctorCheck>} Whether each rendered working directory exists.
+ */
+async function workingDirectoryCheck(renders) {
+  /** @type {string[]} */
+  const missing = []
+  let checked = 0
+
+  for (const render of renders) {
+    if (!render.ok) continue
+
+    checked++
+
+    if (!(await isDirectory(render.cwd))) missing.push(`${render.id} (${render.cwd})`)
+  }
+
+  if (missing.length === 0) {
+    return {detail: `all ${checked} process working ${checked === 1 ? "directory exists" : "directories exist"}`, name: "process working directories", ok: true}
+  }
+
+  return {detail: `missing working ${missing.length === 1 ? "directory" : "directories"}: ${missing.join(", ")}`, name: "process working directories", ok: false}
+}
+
+/**
+ * @param {string} target - Path to test.
+ * @returns {Promise<boolean>} True when the path exists and is a directory.
+ */
+async function isDirectory(target) {
+  try {
+    return (await fs.stat(target)).isDirectory()
+  } catch {
+    return false
+  }
+}

package/src/event-log.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+/**
+ * @typedef {import("./json.js").JsonValue} JsonValue
+ * @typedef {{at: string, data: Record<string, JsonValue>, message: string}} DaemonEvent
+ */
+
+/**
+ * A bounded, in-memory history of structured daemon events (deploys, traffic
+ * switches, stops, crashes, restarts, and failed commands). The newest events
+ * are kept; the oldest are dropped once the limit is exceeded.
+ */
+export default class EventLog {
+  /**
+   * @param {number} limit - Maximum number of events to retain.
+   */
+  constructor(limit) {
+    this.limit = limit
+    this.events = /** @type {DaemonEvent[]} */ ([])
+  }
+
+  /**
+   * Appends an event, dropping the oldest events beyond the limit.
+   * @param {string} message - Event type/message.
+   * @param {Record<string, JsonValue>} data - Structured event payload.
+   * @returns {void}
+   */
+  record(message, data) {
+    this.events.push({at: new Date().toISOString(), data, message})
+
+    if (this.events.length > this.limit) {
+      this.events.splice(0, this.events.length - this.limit)
+    }
+  }
+
+  /**
+   * @param {number} [limit] - Maximum number of most-recent events to return; all when omitted or invalid.
+   * @returns {DaemonEvent[]} The most recent events, oldest first.
+   */
+  recent(limit) {
+    if (typeof limit !== "number" || !Number.isFinite(limit) || limit <= 0 || limit >= this.events.length) {
+      return [...this.events]
+    }
+
+    return this.events.slice(this.events.length - limit)
+  }
+}