@forwardimpact/outpost 3.1.3 → 3.2.0

package/src/scheduler.js

@@ -1,10 +1,43 @@
 /**
  * Scheduler — cron matching, shouldWake logic, wake orchestration.
+ *
+ * The genuine wall-clock read ("what time is it now?") routes through the
+ * injected `runtime.clock` (see `Scheduler#wakeDueAgents` and `failAgent`).
+ * The pure cron helpers below receive that `now` as an explicit `Date` and
+ * construct further `Date` objects only for deterministic date *arithmetic*
+ * over caller-supplied or parsed-from-state inputs (never an ambient no-arg
+ * `new Date()`); the AST checker cannot distinguish the two, so this file is
+ * allow-listed in check-ambient-deps.allow.yml with that reason.
  */
 
+import { isoTimestamp } from "@forwardimpact/libutil";
+
 /** Maximum time an agent can be "active" before being considered stale (35 min). */
 const MAX_AGENT_RUNTIME_MS = 35 * 60_000;
 
+/**
+ * Build a `Date` for "now" from the injected clock's milliseconds. The cron
+ * helpers operate on `Date` objects; this is the single seam that turns the
+ * wall-clock read (`runtime.clock.now()`) into one, so callers in other
+ * modules never construct an ambient `new Date()` themselves.
+ * @param {{now: () => number}} clock
+ * @returns {Date}
+ */
+export function nowFromClock(clock) {
+  return new Date(clock.now());
+}
+
+/**
+ * Format a stored ISO timestamp as a human-readable local time string. Parses
+ * an explicit value (never the wall clock); lives here so the only `new Date`
+ * construction sites stay in this allow-listed module.
+ * @param {string} iso
+ * @returns {string}
+ */
+export function formatLocalTime(iso) {
+  return new Date(Date.parse(iso)).toLocaleString();
+}
+
 // --- Cron matching (pure functions) ------------------------------------------
 
 /**
@@ -133,12 +166,13 @@ export function computeNextWakeAt(agent, agentState, now) {
 /**
  * @param {Object} agentState
  * @param {string} error
+ * @param {number} nowMs - Wall-clock milliseconds (from `runtime.clock.now()`)
  */
-export function failAgent(agentState, error) {
+export function failAgent(agentState, error, nowMs) {
   Object.assign(agentState, {
     status: "failed",
     startedAt: null,
-    lastWokeAt: new Date().toISOString(),
+    lastWokeAt: isoTimestamp(nowMs),
     lastError: String(error).slice(0, 500),
   });
 }
@@ -151,33 +185,38 @@ export class Scheduler {
   #stateManager;
   #agentRunner;
   #log;
+  #clock;
 
   /**
-   * @param {Function} loadConfig - Returns scheduler config
+   * @param {() => Promise<Object>} loadConfig - Returns scheduler config
    * @param {import('./state-manager.js').StateManager} stateManager
    * @param {import('./agent-runner.js').AgentRunner} agentRunner
    * @param {Function} logFn
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+   *   Injected runtime bag (uses `clock` for the wall-clock read).
    */
-  constructor(loadConfig, stateManager, agentRunner, logFn) {
+  constructor(loadConfig, stateManager, agentRunner, logFn, runtime) {
     if (!loadConfig) throw new Error("loadConfig is required");
     if (!stateManager) throw new Error("stateManager is required");
     if (!agentRunner) throw new Error("agentRunner is required");
     if (!logFn) throw new Error("logFn is required");
+    if (!runtime?.clock) throw new Error("runtime.clock is required");
     this.#loadConfig = loadConfig;
     this.#stateManager = stateManager;
     this.#agentRunner = agentRunner;
     this.#log = logFn;
+    this.#clock = runtime.clock;
   }
 
   /**
    * Reset any agents exceeding max runtime, reload config, then wake each agent whose schedule is due.
    */
   async wakeDueAgents() {
-    const config = this.#loadConfig();
-    const state = this.#stateManager.load();
-    const now = new Date();
+    const config = await this.#loadConfig();
+    const state = await this.#stateManager.load();
+    const now = nowFromClock(this.#clock);
 
-    this.#stateManager.resetStaleAgents(
+    await this.#stateManager.resetStaleAgents(
       state,
       { reason: "Exceeded maximum runtime", maxAge: MAX_AGENT_RUNTIME_MS },
       this.#log,

package/src/socket-server.js

@@ -5,18 +5,9 @@
 import { createServer } from "node:net";
 import { createConnection } from "node:net";
 import { createLogger } from "@forwardimpact/libtelemetry";
-import {
-  existsSync,
-  unlinkSync,
-  chmodSync,
-  readdirSync,
-  statSync,
-} from "node:fs";
-
-const logger = createLogger("outpost");
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
-import { computeNextWakeAt } from "./scheduler.js";
+import { computeNextWakeAt, nowFromClock } from "./scheduler.js";
 
 /** Unix-socket IPC server that handles status queries, wake requests, and shutdown commands. */
 export class SocketServer {
@@ -28,6 +19,11 @@ export class SocketServer {
   #cacheDir;
   #daemonStartedAt;
   #server;
+  #fsSync;
+  #clock;
+  #proc;
+  #resolveShutdown;
+  #shutdownPromise;
 
   /**
    * @param {string} socketPath
@@ -38,6 +34,8 @@ export class SocketServer {
    * @param {Function} logFn
    * @param {string} cacheDir
    * @param {number} daemonStartedAt
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+   *   Injected runtime bag (uses `fsSync`, `clock`, `proc`).
    */
   constructor(
     socketPath,
@@ -48,6 +46,7 @@ export class SocketServer {
     logFn,
     cacheDir,
     daemonStartedAt,
+    runtime,
   ) {
     if (!socketPath) throw new Error("socketPath is required");
     if (!scheduler) throw new Error("scheduler is required");
@@ -56,6 +55,9 @@ export class SocketServer {
     if (!loadConfig) throw new Error("loadConfig is required");
     if (!logFn) throw new Error("logFn is required");
     if (!cacheDir) throw new Error("cacheDir is required");
+    if (!runtime?.fsSync) throw new Error("runtime.fsSync is required");
+    if (!runtime?.clock) throw new Error("runtime.clock is required");
+    if (!runtime?.proc) throw new Error("runtime.proc is required");
     this.#socketPath = socketPath;
     this.#agentRunner = agentRunner;
     this.#stateManager = stateManager;
@@ -63,6 +65,21 @@ export class SocketServer {
     this.#log = logFn;
     this.#cacheDir = cacheDir;
     this.#daemonStartedAt = daemonStartedAt;
+    this.#fsSync = runtime.fsSync;
+    this.#clock = runtime.clock;
+    this.#proc = runtime.proc;
+    this.#shutdownPromise = new Promise((r) => {
+      this.#resolveShutdown = r;
+    });
+  }
+
+  /**
+   * Resolves once a shutdown has been requested (via socket or signal). The
+   * daemon awaits this, then the bin translates it to `runtime.proc.exit(0)`.
+   * @returns {Promise<void>}
+   */
+  whenStopped() {
+    return this.#shutdownPromise;
   }
 
   /**
@@ -90,13 +107,13 @@ export class SocketServer {
    * @returns {string|null}
    */
   #latestFileByMtime(dir, filter) {
-    const matches = readdirSync(dir).filter(filter);
+    const matches = this.#fsSync.readdirSync(dir).filter(filter);
     if (matches.length === 0) return null;
     let latest = join(dir, matches[0]);
-    let latestMtime = statSync(latest).mtimeMs;
+    let latestMtime = this.#fsSync.statSync(latest).mtimeMs;
     for (let i = 1; i < matches.length; i++) {
       const p = join(dir, matches[i]);
-      const mt = statSync(p).mtimeMs;
+      const mt = this.#fsSync.statSync(p).mtimeMs;
       if (mt > latestMtime) {
         latest = p;
         latestMtime = mt;
@@ -113,7 +130,7 @@ export class SocketServer {
    */
   #resolveBriefingFile(agentName, agentConfig) {
     const stateDir = join(this.#cacheDir, "state");
-    if (existsSync(stateDir)) {
+    if (this.#fsSync.existsSync(stateDir)) {
       const prefix = agentName.replace(/-/g, "_") + "_";
       const found = this.#latestFileByMtime(
         stateDir,
@@ -128,8 +145,9 @@ export class SocketServer {
         "knowledge",
         "Briefings",
       );
-      if (existsSync(dir)) {
-        const files = readdirSync(dir)
+      if (this.#fsSync.existsSync(dir)) {
+        const files = this.#fsSync
+          .readdirSync(dir)
           .filter((f) => f.endsWith(".md"))
           .sort()
           .reverse();
@@ -143,10 +161,10 @@ export class SocketServer {
   /**
    * @param {import('node:net').Socket} socket
    */
-  #handleStatusRequest(socket) {
-    const config = this.#loadConfig();
-    const state = this.#stateManager.load();
-    const now = new Date();
+  async #handleStatusRequest(socket) {
+    const config = await this.#loadConfig();
+    const state = await this.#stateManager.load();
+    const now = nowFromClock(this.#clock);
     const agents = {};
 
     for (const [name, agent] of Object.entries(config.agents)) {
@@ -169,7 +187,7 @@ export class SocketServer {
     this.#send(socket, {
       type: "status",
       uptime: this.#daemonStartedAt
-        ? Math.floor((Date.now() - this.#daemonStartedAt) / 1000)
+        ? Math.floor((this.#clock.now() - this.#daemonStartedAt) / 1000)
         : 0,
       agents,
     });
@@ -179,7 +197,7 @@ export class SocketServer {
    * @param {import('node:net').Socket} socket
    * @param {string} line
    */
-  #handleMessage(socket, line) {
+  async #handleMessage(socket, line) {
     let request;
     try {
       request = JSON.parse(line);
@@ -194,8 +212,8 @@ export class SocketServer {
       this.#log("Shutdown requested via socket.");
       this.#send(socket, { type: "ack", command: "shutdown" });
       socket.end();
-      this.#agentRunner.killActiveChildren();
-      process.exit(0);
+      this.#requestShutdown();
+      return;
     }
 
     if (request.type === "wake") {
@@ -203,7 +221,7 @@ export class SocketServer {
         this.#send(socket, { type: "error", message: "Missing agent name" });
         return;
       }
-      const config = this.#loadConfig();
+      const config = await this.#loadConfig();
       const agent = config.agents[request.agent];
       if (!agent) {
         this.#send(socket, {
@@ -217,7 +235,7 @@ export class SocketServer {
         command: "wake",
         agent: request.agent,
       });
-      const state = this.#stateManager.load();
+      const state = await this.#stateManager.load();
       this.#agentRunner
         .wake(request.agent, agent, state, config.env)
         .catch(() => {});
@@ -231,12 +249,27 @@ export class SocketServer {
   }
 
   /**
-   * Remove any existing socket file, bind the server, and register SIGTERM/SIGINT handlers to kill active children before exit.
+   * Tear down active children and the listening socket, then signal the daemon
+   * (via `whenStopped`) that it is safe to exit. The bin owns the actual
+   * `runtime.proc.exit` call (design Decision 4).
+   */
+  #requestShutdown() {
+    this.#agentRunner.killActiveChildren();
+    if (this.#server) this.#server.close();
+    try {
+      this.#fsSync.unlinkSync(this.#socketPath);
+    } catch {}
+    this.#resolveShutdown();
+  }
+
+  /**
+   * Remove any existing socket file, bind the server, and register
+   * SIGTERM/SIGINT handlers that request a graceful shutdown.
    * @returns {import('node:net').Server}
    */
   start() {
     try {
-      unlinkSync(this.#socketPath);
+      this.#fsSync.unlinkSync(this.#socketPath);
     } catch {}
 
     this.#server = createServer((socket) => {
@@ -247,14 +280,14 @@ export class SocketServer {
         while ((idx = buffer.indexOf("\n")) !== -1) {
           const line = buffer.slice(0, idx).trim();
           buffer = buffer.slice(idx + 1);
-          if (line) this.#handleMessage(socket, line);
+          if (line) void this.#handleMessage(socket, line);
         }
       });
       socket.on("error", () => {});
     });
 
     this.#server.listen(this.#socketPath, () => {
-      chmodSync(this.#socketPath, 0o600);
+      this.#fsSync.chmodSync(this.#socketPath, 0o600);
       this.#log(`Socket server listening on ${this.#socketPath}`);
     });
 
@@ -262,16 +295,8 @@ export class SocketServer {
       this.#log(`Socket server error: ${err.message}`);
     });
 
-    const cleanup = () => {
-      this.#agentRunner.killActiveChildren();
-      this.#server.close();
-      try {
-        unlinkSync(this.#socketPath);
-      } catch {}
-      process.exit(0);
-    };
-    process.on("SIGTERM", cleanup);
-    process.on("SIGINT", cleanup);
+    this.#proc.on("SIGTERM", () => this.#requestShutdown());
+    this.#proc.on("SIGINT", () => this.#requestShutdown());
 
     return this.#server;
   }
@@ -284,7 +309,7 @@ export class SocketServer {
       this.#server.close();
     }
     try {
-      unlinkSync(this.#socketPath);
+      this.#fsSync.unlinkSync(this.#socketPath);
     } catch {}
   }
 }
@@ -292,16 +317,21 @@ export class SocketServer {
 /**
  * Connect to the daemon socket and request graceful shutdown.
  * @param {string} socketPath
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ *   Injected runtime bag (uses `fsSync` and `clock`).
  * @returns {Promise<boolean>}
  */
-export async function requestShutdown(socketPath) {
-  if (!existsSync(socketPath)) {
+export async function requestShutdown(socketPath, runtime) {
+  if (!runtime?.fsSync) throw new Error("runtime.fsSync is required");
+  if (!runtime?.clock) throw new Error("runtime.clock is required");
+  const logger = createLogger("outpost", runtime);
+  if (!runtime.fsSync.existsSync(socketPath)) {
     logger.info("Daemon not running (no socket).");
     return false;
   }
 
   return new Promise((resolve) => {
-    const timeout = setTimeout(() => {
+    const timeout = runtime.clock.setTimeout(() => {
       logger.info("Shutdown timed out.");
       socket.destroy();
       resolve(false);
@@ -315,7 +345,7 @@ export async function requestShutdown(socketPath) {
     socket.on("data", (data) => {
       buffer += data.toString();
       if (buffer.includes("\n")) {
-        clearTimeout(timeout);
+        runtime.clock.clearTimeout(timeout);
         logger.info("Daemon stopped.");
         socket.destroy();
         resolve(true);
@@ -323,13 +353,13 @@ export async function requestShutdown(socketPath) {
     });
 
     socket.on("error", () => {
-      clearTimeout(timeout);
+      runtime.clock.clearTimeout(timeout);
       logger.info("Daemon not running (connection refused).");
       resolve(false);
     });
 
     socket.on("close", () => {
-      clearTimeout(timeout);
+      runtime.clock.clearTimeout(timeout);
       resolve(true);
     });
   });

package/src/state-manager.js

@@ -2,41 +2,46 @@
  * StateManager — load/save state.json, reset stale agents.
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { isoTimestamp } from "@forwardimpact/libutil";
 
 /** Persist and query agent scheduler state from a JSON file on disk. */
 export class StateManager {
   #statePath;
   #fs;
+  #clock;
 
   /**
    * @param {string} statePath - Path to state.json
-   * @param {{ readFileSync: Function, writeFileSync: Function, mkdirSync: Function }} fs
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+   *   Injected runtime bag (uses `fs` (async) and `clock`).
    */
-  constructor(statePath, fs) {
+  constructor(statePath, runtime) {
     if (!statePath) throw new Error("statePath is required");
-    if (!fs) throw new Error("fs is required");
+    if (!runtime?.fs) throw new Error("runtime.fs is required");
+    if (!runtime?.clock) throw new Error("runtime.clock is required");
     this.#statePath = statePath;
-    this.#fs = fs;
+    this.#fs = runtime.fs;
+    this.#clock = runtime.clock;
   }
 
   /**
-   * Read and parse state from disk; on any read or parse error, write a fresh empty state and return it.
-   * @returns {Object}
+   * Read and parse state from disk; on any read or parse error, write a fresh
+   * empty state and return it.
+   * @returns {Promise<Object>}
    */
-  load() {
+  async load() {
     try {
-      const raw = JSON.parse(this.#fs.readFileSync(this.#statePath, "utf8"));
+      const raw = JSON.parse(await this.#fs.readFile(this.#statePath, "utf8"));
       if (!raw || typeof raw !== "object" || !raw.agents) {
         const state = { agents: {} };
-        this.save(state);
+        await this.save(state);
         return state;
       }
       return raw;
     } catch {
       const state = { agents: {} };
-      this.save(state);
+      await this.save(state);
       return state;
     }
   }
@@ -44,10 +49,11 @@ export class StateManager {
   /**
    * Save state to disk
    * @param {Object} state
+   * @returns {Promise<void>}
    */
-  save(state) {
-    this.#fs.mkdirSync(dirname(this.#statePath), { recursive: true });
-    this.#fs.writeFileSync(
+  async save(state) {
+    await this.#fs.mkdir(dirname(this.#statePath), { recursive: true });
+    await this.#fs.writeFile(
       this.#statePath,
       JSON.stringify(state, null, 2) + "\n",
     );
@@ -58,14 +64,14 @@ export class StateManager {
    * @param {Object} state
    * @param {{ reason: string, maxAge?: number }} opts
    * @param {Function} logFn
-   * @returns {number} Number of agents reset
+   * @returns {Promise<number>} Number of agents reset
    */
-  resetStaleAgents(state, { reason, maxAge }, logFn) {
+  async resetStaleAgents(state, { reason, maxAge }, logFn) {
     let resetCount = 0;
     for (const [name, as] of Object.entries(state.agents)) {
       if (as.status !== "active") continue;
       if (maxAge && as.startedAt) {
-        const elapsed = Date.now() - new Date(as.startedAt).getTime();
+        const elapsed = this.#clock.now() - Date.parse(as.startedAt);
         if (elapsed < maxAge) continue;
       }
       logFn(`Resetting stale agent: ${name} (${reason})`);
@@ -76,7 +82,7 @@ export class StateManager {
       });
       resetCount++;
     }
-    if (resetCount > 0) this.save(state);
+    if (resetCount > 0) await this.save(state);
     return resetCount;
   }
 
@@ -86,8 +92,9 @@ export class StateManager {
    * @param {string} stdout
    * @param {string} agentName
    * @param {string} cacheDir - Cache directory for state files
+   * @returns {Promise<void>}
    */
-  updateAgentState(agentState, stdout, agentName, cacheDir) {
+  async updateAgentState(agentState, stdout, agentName, cacheDir) {
     const lines = stdout.split("\n");
     const decisionLine = lines.find((l) => l.startsWith("Decision:"));
     const actionLine = lines.find((l) => l.startsWith("Action:"));
@@ -95,7 +102,7 @@ export class StateManager {
     Object.assign(agentState, {
       status: "idle",
       startedAt: null,
-      lastWokeAt: new Date().toISOString(),
+      lastWokeAt: isoTimestamp(this.#clock.now()),
       lastDecision: decisionLine
         ? decisionLine.slice(10).trim()
         : stdout.slice(0, 200),
@@ -106,21 +113,11 @@ export class StateManager {
 
     // Save output as briefing fallback
     const stateDir = join(cacheDir, "state");
-    this.#fs.mkdirSync(stateDir, { recursive: true });
+    await this.#fs.mkdir(stateDir, { recursive: true });
     const prefix = agentName.replace(/-/g, "_");
-    this.#fs.writeFileSync(join(stateDir, `${prefix}_last_output.md`), stdout);
+    await this.#fs.writeFile(
+      join(stateDir, `${prefix}_last_output.md`),
+      stdout,
+    );
   }
 }
-
-/**
- * Create a StateManager with real fs dependencies
- * @param {string} statePath
- * @returns {StateManager}
- */
-export function createStateManager(statePath) {
-  return new StateManager(statePath, {
-    readFileSync,
-    writeFileSync,
-    mkdirSync,
-  });
-}