@forwardimpact/outpost 3.11.0 → 3.12.1

package/README.md

@@ -2,8 +2,8 @@
 
 <!-- BEGIN:description — Do not edit. Generated from package.json. -->
 
-Personal operations center — context from email, calendar, and knowledge
-assembled so preparation is continuous, not a morning scramble.
+Personal operations center — context assembled from email, calendar, and
+knowledge so preparation is continuous instead of a morning scramble.
 
 <!-- END:description -->
 

package/bin/fit-outpost.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-// Thin entry point — the sole construction site for the runtime collaborator
-// bag, threaded into src/outpost.js's dispatch via run(runtime, version).
+// This file is the thin entry point. It is the sole construction site for the
+// runtime collaborator bag. It threads that bag into the dispatch in
+// src/outpost.js through run(runtime, version).
 import "@forwardimpact/libpreflight/node22";
 
 import { resolveVersion } from "@forwardimpact/libcli";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forwardimpact/outpost",
-  "version": "3.11.0",
-  "description": "Personal operations center — context from email, calendar, and knowledge assembled so preparation is continuous, not a morning scramble.",
+  "version": "3.12.1",
+  "description": "Personal operations center — context assembled from email, calendar, and knowledge so preparation is continuous instead of a morning scramble.",
   "homepage": "https://www.forwardimpact.team",
   "repository": {
     "type": "git",
@@ -14,12 +14,12 @@
     {
       "user": "Empowered Engineers",
       "goal": "Be Prepared and Productive",
-      "trigger": "Walking into a meeting cold because context was scattered across email, Slack, and last week's notes.",
+      "trigger": "The engineer walks into a meeting cold because context is scattered across email, Slack, and last week's notes.",
       "bigHire": "keep track of people, projects, and threads without depending on memory.",
       "littleHire": "walk into every meeting already oriented.",
       "competesWith": "morning email scan; re-reading calendar invites; personal notes; asking colleagues for context",
       "forces": {
-        "push": "Context-switching compounds; starting cold wastes everyone's time.",
+        "push": "Context-switching compounds. Starting cold wastes everyone's time.",
         "pull": "Continuous awareness without continuous effort — context assembled.",
         "habit": "Morning routines and tracking systems that feel 'good enough.'",
         "anxiety": "Delegating awareness to a system feels like losing control."

package/src/agent-path.js

@@ -1,15 +1,19 @@
 /**
- * agent-path — validate a config-supplied agent name before using it as a
+ * agent-path — validate a config-supplied agent name before you use it as a
  * filesystem path component.
  *
  * The agent-state writer maps an agent name to a per-agent state filename.
- * A name carrying `/` or `..` segments would let a rewritten `scheduler.json`
- * direct writes outside `~/.cache/fit/outpost/state/`. This module validates
- * and rejects rather than silently sanitising, so an unexpected path segment
- * surfaces as an intrusion signal instead of a quietly rewritten filename.
+ * A name that carries `/` or `..` segments would let a rewritten
+ * `scheduler.json` direct writes outside `~/.cache/fit/outpost/state/`. This
+ * module validates the name and rejects an unsafe one. It never sanitises the
+ * name silently. So an unexpected path segment surfaces as an intrusion
+ * signal. It does not become a quietly rewritten filename.
  */
 
-/** Raised when an agent name cannot map to a safe state-file prefix. */
+/**
+ * `agentNameToStatePrefix` raises this when an agent name cannot map to a
+ * safe state-file prefix.
+ */
 export class UnsafeAgentNameError extends Error {
   /** @param {string} name */
   constructor(name) {

package/src/agent-runner.js

@@ -15,14 +15,14 @@ import { resolvePrivilege, disclaimFor } from "./privilege.js";
 import { buildSpawnEnv } from "./spawn-env.js";
 
 /**
- * System-prompt directive injected under the `brief` posture. Neutralises any
- * draft-side prose in a materialised agent definition and forbids writing the
- * posture record.
+ * The system-prompt directive the runner injects under the `brief` posture. It
+ * neutralises any draft-side prose in a materialised agent definition. It also
+ * forbids a write to the posture record.
  */
 const BRIEF_DIRECTIVE =
   "Adoption posture: brief. Run only read-and-brief work. Do not draft or " +
-  "send content on the user's behalf for delivery to anyone else, do not move " +
-  "or write files outside the knowledge base, and never write the posture " +
+  "send content on the user's behalf for delivery to anyone else. Do not " +
+  "move or write files outside the knowledge base. Never write the posture " +
   "record (~/.fit/outpost/posture.json).";
 
 /** Spawn agent CLI processes, capture their output, and update agent state. */
@@ -41,11 +41,11 @@ export class AgentRunner {
 
   /**
    * @param {Object | (() => Object | Promise<{default?: Object}>)} spawn -
-   *   The posix-spawn module, or a (possibly async) loader returning it. A
-   *   loader lets the Bun-FFI module load lazily so plain `node` invocations
-   *   that never wake an agent don't pull in `bun:ffi`.
+   *   The posix-spawn module, or a loader that returns it. The loader may be
+   *   async. A loader lets the Bun-FFI module load lazily. So a plain `node`
+   *   invocation that never wakes an agent does not pull in `bun:ffi`.
    * @param {import('./state-manager.js').StateManager} stateManager
-   * @param {Function} logFn - Logging function
+   * @param {Function} logFn - The function that writes a log line
    * @param {string} cacheDir - Cache directory for state files
    * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
    *   Injected runtime bag (uses `fs` (async), `proc`, `clock`).
@@ -84,8 +84,8 @@ export class AgentRunner {
   }
 
   /**
-   * Resolve the injected spawn collaborator to the posix-spawn module,
-   * invoking and unwrapping a loader thunk on first use.
+   * Resolve the injected spawn collaborator to the posix-spawn module. On
+   * first use, invoke a loader thunk and unwrap it.
    * @returns {Promise<Object>}
    */
   async #resolveSpawn() {
@@ -97,7 +97,7 @@ export class AgentRunner {
   }
 
   /**
-   * Test whether a path exists, via the async fs surface.
+   * Test whether a path exists, through the async fs surface.
    * @param {string} p
    * @returns {Promise<boolean>}
    */
@@ -148,11 +148,12 @@ export class AgentRunner {
   }
 
   /**
-   * Resolve the spawn flags the recorded posture adds. Under `brief` (also the
-   * default when no posture is recorded), deny every draft-side skill by name
-   * and inject the brief directive — a deterministic gate the woken agent
-   * cannot override under `bypassPermissions`. Under `brief+draft`, add
-   * nothing. The posture record is read here, never written.
+   * Resolve the spawn flags the recorded posture adds. Under `brief`, deny
+   * every draft-side skill by name and inject the brief directive. `brief` is
+   * also the default when no posture is recorded. The directive is a
+   * deterministic gate. The woken agent cannot override it under
+   * `bypassPermissions`. Under `brief+draft`, add nothing. This method reads
+   * the posture record. It never writes the record.
    * @returns {Promise<string[]>} Extra args to append to the spawn argv.
    */
   async #postureArgs() {
@@ -170,17 +171,20 @@ export class AgentRunner {
   }
 
   /**
-   * Validate the agent's kb path exists, spawn `claude --agent` with the prompt "Observe and act.", and update agent state to active/idle/failed.
+   * Validate that the agent's kb path exists. Spawn `claude --agent` with the
+   * prompt "Observe and act." Then update the agent state to active, idle, or
+   * failed.
    * @param {string} agentName
    * @param {Object} agent
    * @param {Object} state
    * @param {Record<string, string>} [configEnv] - Extra env vars from config
    */
   async wake(agentName, agent, state, configEnv) {
-    // Resolve the mandatory privilege level before any work. A missing or
-    // invalid level is fail-closed: log and skip the wake — no agent process is
-    // spawned with a guessed privilege. The level lives in the user-only trust
-    // root, so a spawned agent cannot raise its own.
+    // Resolve the mandatory privilege level before any work. The runner is
+    // fail-closed on a missing or invalid level. It logs the problem and skips
+    // the wake. It never spawns an agent process with a guessed privilege. The
+    // level lives in the user-only trust root, so a spawned agent cannot raise
+    // its own.
     let level;
     try {
       level = resolvePrivilege(agent);
@@ -196,13 +200,13 @@ export class AgentRunner {
     }
 
     if (!agent.kb) {
-      this.#log(`Agent ${agentName}: no "kb" specified, skipping.`);
+      this.#log(`Agent ${agentName}: no "kb" specified. Skipped.`);
       return;
     }
     const kbPath = this.#expandPath(agent.kb);
     if (!(await this.#exists(kbPath))) {
       this.#log(
-        `Agent ${agentName}: path "${kbPath}" does not exist, skipping.`,
+        `Agent ${agentName}: path "${kbPath}" does not exist. Skipped.`,
       );
       return;
     }

package/src/index.js

@@ -1,5 +1,4 @@
 // Public entry point for @forwardimpact/outpost.
-// Outpost is primarily a CLI — this file exists so the package conforms
-// to the repo-wide layout contract. The runtime CLI dispatch lives in
-// src/outpost.js.
+// Outpost is primarily a CLI. This file exists so the package conforms to the
+// repo-wide layout contract. The runtime CLI dispatch lives in src/outpost.js.
 export * from "./outpost.js";

package/src/kb-manager.js

@@ -6,7 +6,7 @@ import { join, dirname, resolve, basename } from "node:path";
 import { homedir } from "node:os";
 import { createLogger } from "@forwardimpact/libtelemetry";
 
-/** Manage knowledge base lifecycle including initialization, updates, and settings merging. */
+/** Manage the knowledge base lifecycle: init, update, and settings merge. */
 export class KBManager {
   #fs;
   #logger;
@@ -25,12 +25,13 @@ export class KBManager {
 
   /**
    * Resolve a knowledge-base name to its path under the XDG data home,
-   * `~/.local/share/fit/outpost/<name>`. The argument is a single path segment,
-   * never an arbitrary filesystem path, so a provisioned KB always lands outside
-   * TCC-protected folders. The name is validated — not sanitised — against the
-   * same rule as `agent-path.js`: a name carrying `/`, `\`, `..`, NUL, or a
-   * leading `~` could steer the KB back inside `~/Documents`, reopening the TCC
-   * hole, so it is rejected rather than rewritten.
+   * `~/.local/share/fit/outpost/<name>`. The argument is a single path
+   * segment. It is never an arbitrary filesystem path. So a provisioned KB
+   * always lands outside TCC-protected folders. This method validates the name
+   * against the same rule as `agent-path.js`. It does not sanitise the name. A
+   * name that carries `/`, `\`, `..`, NUL, or a leading `~` could steer the KB
+   * back inside `~/Documents` and reopen the TCC hole. So this method rejects
+   * the name. It never rewrites the name.
    * @param {string} name - The KB name (e.g. `Team`, `personal`).
    * @returns {string} Absolute path under the data home.
    * @throws {Error} when `name` is empty, non-string, or an unsafe segment.
@@ -51,7 +52,7 @@ export class KBManager {
   }
 
   /**
-   * Test whether a path exists, via the async fs surface.
+   * Test whether a path exists, through the async fs surface.
    * @param {string} p
    * @returns {Promise<boolean>}
    */
@@ -94,7 +95,7 @@ export class KBManager {
   }
 
   /**
-   * Copy bundled files (CLAUDE.md, skills, agents) from template to a KB.
+   * Copy bundled files (CLAUDE.md, skills, agents) from the template to a KB.
    * @param {string} tpl - Path to the template directory
    * @param {string} dest - Path to the target knowledge base
    * @returns {Promise<void>}
@@ -156,7 +157,7 @@ export class KBManager {
   }
 
   /**
-   * Merge template settings.json into the destination's settings.json.
+   * Merge the template settings.json into the destination's settings.json.
    * @param {string} tpl - Template directory
    * @param {string} dest - Knowledge base directory
    * @returns {Promise<void>}
@@ -206,10 +207,10 @@ export class KBManager {
     }
 
     await this.#ensureDir(dest);
-    // Create the top-level roots only. `Knowledge/` is the shared graph (synced
-    // with the team); `Drafts/` and `Briefings/` are personal and local. Entity
-    // subdirectories (People, Organizations, ...) are created on demand by the
-    // skills that write into them.
+    // Create the top-level roots only. `Knowledge/` is the shared graph, and
+    // the team syncs it. `Drafts/` and `Briefings/` are personal and local.
+    // The skills that write into the entity subdirectories (People,
+    // Organizations, ...) create them on demand.
     for (const d of ["Knowledge", "Drafts", "Briefings"])
       await this.#ensureDir(join(dest, d));
 
@@ -223,12 +224,13 @@ export class KBManager {
   }
 
   /**
-   * Create a navigation symlink at `~/Documents/<name>` pointing to the KB.
+   * Create a navigation symlink at `~/Documents/<name>` that points to the KB.
    * The KB data itself stays under the XDG data home, outside TCC-protected
-   * folders — this is only a convenience pointer so the KB is easy to find and
-   * open from Finder. Best-effort: a pre-existing entry is left untouched, and
-   * any failure (e.g. macOS denying write access to `~/Documents`) is logged,
-   * never fatal, because the KB is already provisioned at `dest`.
+   * folders. The symlink is only a convenience pointer. It makes the KB easy
+   * to find and open from Finder. The method is best-effort. It leaves a
+   * pre-existing entry untouched. It logs any failure, for example when macOS
+   * denies write access to `~/Documents`. A failure is never fatal, because
+   * the KB is already provisioned at `dest`.
    * @param {string} dest - Absolute path to the provisioned KB.
    * @returns {Promise<void>}
    */

package/src/outpost.js

@@ -11,10 +11,11 @@
 //   fit-outpost status              Show agent status
 //   fit-outpost --help              Show this help
 //
-// This module owns the CLI definition and dispatch table. The runtime
-// collaborator bag is constructed once in bin/fit-outpost.js (the sole
-// construction site) and threaded into `run(runtime, version)`; `run` returns
-// the process exit code and the bin translates it to `runtime.proc.exit`.
+// This module owns the CLI definition and dispatch table. bin/fit-outpost.js
+// constructs the runtime collaborator bag once. That file is the sole
+// construction site. It threads the bag into `run(runtime, version)`. `run`
+// returns the process exit code. The bin translates that code to
+// `runtime.proc.exit`.
 
 import { join, dirname, resolve } from "node:path";
 import { homedir } from "node:os";
@@ -38,9 +39,9 @@ import {
 const SHARE_DIR = "/usr/local/share/fit-outpost";
 
 /**
- * Build the CLI definition. The object is byte-identical to the libcli
- * definition the goldens were captured against, so `--help` / `--version`
- * output stays stable.
+ * Build the CLI definition. This object is byte-identical to the libcli
+ * definition that the golden capture used. So `--help` and `--version` output
+ * stays stable.
  * @param {string} version
  * @returns {object}
  */
@@ -111,7 +112,7 @@ function buildDefinition(version) {
 }
 
 /**
- * Render an agent's multi-line status block (pure formatting).
+ * Render an agent's multi-line status block. This is a pure format step.
  * @param {string} name
  * @param {Object} agent
  * @param {Object} s - The agent's persisted state.
@@ -145,7 +146,8 @@ export async function run(runtime, version) {
   const logger = createLogger("outpost", runtime);
 
   /**
-   * Async existence check via the one fs surface this module uses.
+   * Test whether a path exists, through the one async fs surface this module
+   * uses.
    * @param {string} p
    * @returns {Promise<boolean>}
    */
@@ -193,10 +195,10 @@ export async function run(runtime, version) {
   }
 
   // --- Wire dependencies -----------------------------------------------------
-  // posix-spawn is a Bun-FFI module (`bun:ffi`); importing it eagerly would
-  // crash plain `node` (e.g. `--help`/`--version`/golden capture). Load it
-  // lazily so only an actual agent wake — which only runs under Bun on macOS —
-  // pulls it in.
+  // posix-spawn is a Bun-FFI module (`bun:ffi`). An eager import would crash
+  // plain `node` (e.g. `--help`/`--version`/golden capture). So load it
+  // lazily. Then only an actual agent wake pulls it in. That wake only runs
+  // under Bun on macOS.
   const loadSpawn = () => import("@forwardimpact/libmacos/posix-spawn");
   const stateManager = new StateManager(STATE_PATH, runtime);
   const agentRunner = new AgentRunner(
@@ -247,7 +249,7 @@ export async function run(runtime, version) {
   // --- Daemon ----------------------------------------------------------------
   async function daemon() {
     const daemonStartedAt = clock.now();
-    log("Scheduler daemon started. Polling every 60 seconds.");
+    log("Scheduler daemon started. It polls every 60 seconds.");
     log(`Config: ${CONFIG_PATH}  State: ${STATE_PATH}`);
 
     // Reset any agents left "active" from a previous daemon session.
@@ -276,8 +278,8 @@ export async function run(runtime, version) {
     void socketServer.whenStopped().then(() => {
       stopped = true;
       // Cancel any pending poll so the armed timer does not keep the event
-      // loop alive after shutdown — `run()` returns 0 and the bin exits only
-      // on a nonzero code, so a lingering 60s timer would delay exit.
+      // loop alive after shutdown. `run()` returns 0, and the bin exits only
+      // on a nonzero code. So a 60s timer that stays armed would delay exit.
       if (tickHandle !== undefined) clock.clearTimeout(tickHandle);
     });
 
@@ -292,8 +294,8 @@ export async function run(runtime, version) {
     }
     void tick();
 
-    // Block until a shutdown is requested via socket or signal; the bin then
-    // owns the process-exit call.
+    // Block until a socket or a signal requests a shutdown. The bin then owns
+    // the process-exit call.
     await socketServer.whenStopped();
     return 0;
   }
@@ -323,9 +325,9 @@ export async function run(runtime, version) {
     const state = await stateManager.load();
     const posture = await readPosture(fs, POSTURE_PATH);
     logger.info("\nOutpost Scheduler\n==================\n");
-    // The posture must be observable on a line matching
-    // `^posture: (brief|brief+draft|unset)$`, so write it as plain text to
-    // stdout rather than through the RFC5424-prefixed logger.
+    // The posture must be observable on a line that matches
+    // `^posture: (brief|brief+draft|unset)$`. So write it as plain text to
+    // stdout. Do not write it through the RFC5424-prefixed logger.
     proc.stdout.write(`posture: ${posture ?? "unset"}\n`);
 
     const agents = Object.entries(config.agents || {});
@@ -409,13 +411,14 @@ export async function run(runtime, version) {
         cli.usageError("missing required argument <agent>");
         return 2;
       }
-      // Always route the wake through the running daemon. The daemon is the
-      // only spawn site that descends from fit-outpost.app, so a `claude`
-      // spawned there inherits the app as its TCC responsible process and a
-      // single grant to the app covers it. Spawning from this CLI process
-      // would attribute the access to the terminal instead, breaking the
-      // single-grant model. If no daemon is running there is nowhere to wake
-      // with correct attribution, so this errors rather than spawning locally.
+      // Always route the wake through the daemon that already runs. The daemon
+      // is the only spawn site that descends from fit-outpost.app. So a
+      // `claude` spawned there inherits the app as its TCC responsible
+      // process, and a single grant to the app covers it. A spawn from this
+      // CLI process would attribute the access to the terminal instead. That
+      // breaks the single-grant model. When no daemon runs, there is nowhere
+      // to wake with correct attribution. So this command errors. It does not
+      // spawn locally.
       const result = await requestWake(SOCKET_PATH, args[0], runtime);
       if (result.ok) {
         log(`Wake dispatched to daemon for "${args[0]}".`);
@@ -423,7 +426,7 @@ export async function run(runtime, version) {
       }
       if (result.reason === "not-running") {
         cli.error(
-          "daemon not running. Start fit-outpost.app (or run `fit-outpost daemon`) before waking an agent.",
+          "daemon not running. Start fit-outpost.app (or run `fit-outpost daemon`) before you wake an agent.",
         );
       } else if (result.reason === "timeout") {
         cli.error("daemon did not respond to the wake request.");
@@ -434,8 +437,9 @@ export async function run(runtime, version) {
     },
     init: async () => {
       // `init [name]` provisions a KB by name under the data home (default
-      // `Team`), never an arbitrary path — so the substrate cannot be
-      // steered back into a TCC-protected folder. An unsafe name is refused.
+      // `Team`). It never accepts an arbitrary path. So nobody can steer the
+      // substrate back into a TCC-protected folder. This command refuses an
+      // unsafe name.
       const name = args[0] ?? "Team";
       let target;
       try {
@@ -452,8 +456,8 @@ export async function run(runtime, version) {
         return result.code;
       }
       // A fresh init defaults the posture to `brief`, the opted-into trust
-      // contract. Only write when none is recorded so re-running never flips
-      // an existing posture.
+      // contract. Only write when no posture is recorded. A later run then
+      // never flips an existing posture.
       if ((await readPosture(fs, POSTURE_PATH)) === null) {
         await writePosture(fs, POSTURE_PATH, "brief");
       }

package/src/posture.js

@@ -2,7 +2,7 @@
  * Posture — read/write the adoption-posture record and resolve the
  * draft-side deny set from the skill-posture manifest.
  *
- * The two committed posture strings are the only valid values; they appear
+ * The two committed posture strings are the only valid values. They appear
  * verbatim in CLI flags, `status` output, and landing-page copy.
  */
 
@@ -46,8 +46,8 @@ export async function writePosture(fs, posturePath, value) {
 }
 
 /**
- * Resolve the effective posture, applying the default when no posture has been
- * recorded so a posture-less install behaves as `brief`.
+ * Resolve the effective posture. Apply the default when no posture is
+ * recorded. A posture-less install then behaves as `brief`.
  * @param {"brief"|"brief+draft"|null} stored
  * @returns {"brief"|"brief+draft"}
  */

package/src/privilege.js

@@ -3,23 +3,23 @@
  * the hop-2 spawn disclaim flag.
  *
  * The level governs the macOS reach the daemon grants a woken agent. `full`
- * keeps today's single-grant model (the child inherits `fit-outpost.app` as its
- * responsible process, so Full Disk Access and Automation flow to it); a
- * `restricted` agent is held responsible for itself, so those grants are not
- * extended and it can reach only non-TCC-protected substrate.
+ * keeps today's single-grant model. The child inherits `fit-outpost.app` as its
+ * responsible process, so Full Disk Access and Automation flow to it. A
+ * `restricted` agent is responsible for itself. Those grants do not extend to
+ * it, so it can reach only non-TCC-protected substrate.
  *
- * The level is mandatory and lives in the same user-only trust root as the
- * spawn-env allow-set and the state roots, so an agent cannot raise its own
- * level. Patterned on `posture.js` but with no `effective*` coercion and no
- * default — a missing or unrecognised value throws.
+ * The level is mandatory. It lives in the same user-only trust root as the
+ * spawn-env allow-set and the state roots. So an agent cannot raise its own
+ * level. This module follows the `posture.js` pattern, with no `effective*`
+ * coercion and no default. A missing or unrecognised value throws.
  */
 
 /** The two privilege levels, in declaration order. */
 export const PRIVILEGE_LEVELS = ["full", "restricted"];
 
 /**
- * Resolve an agent's declared privilege level. The level is mandatory: a
- * missing or unrecognised value throws — there is no default.
+ * Resolve an agent's declared privilege level. The level is mandatory. A
+ * missing or unrecognised value throws. There is no default.
  * @param {{ privilege?: string }} agent - One agent's config.
  * @returns {"full"|"restricted"} The declared level.
  * @throws {Error} when `agent.privilege` is not one of {@link PRIVILEGE_LEVELS}.
@@ -35,7 +35,7 @@ export function resolvePrivilege(agent) {
 }
 
 /**
- * Map a level to the hop-2 disclaim flag: `restricted` self-disclaims (`1`),
+ * Map a level to the hop-2 disclaim flag. `restricted` self-disclaims (`1`).
  * `full` keeps the inherited responsible process (`0`).
  * @param {"full"|"restricted"} level
  * @returns {0|1}

package/src/scheduler.js

@@ -3,23 +3,24 @@
  *
  * 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
+ * The pure cron helpers below receive that `now` as an explicit `Date`. They
  * 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 .coaligned/invariants/ambient-deps.allow.yml with that reason.
+ * `new Date()`). The AST checker cannot distinguish the two, so
+ * .jidoka/invariants/ambient-deps.allow.yml allow-lists this file with that
+ * reason.
  */
 
 import { isoTimestamp } from "@forwardimpact/libutil";
 
-/** Maximum time an agent can be "active" before being considered stale (35 min). */
+/** Maximum time an agent can be "active" before it becomes 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.
+ * helpers operate on `Date` objects. This function 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}
  */
@@ -28,9 +29,9 @@ export function nowFromClock(clock) {
 }
 
 /**
- * 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.
+ * Format a stored ISO timestamp as a human-readable local time string. This
+ * function parses an explicit value (never the wall clock). It lives here so
+ * the only `new Date` construction sites stay in this allow-listed module.
  * @param {string} iso
  * @returns {string}
  */
@@ -179,7 +180,7 @@ export function failAgent(agentState, error, nowMs) {
 
 // --- Scheduler class ---------------------------------------------------------
 
-/** Orchestrate periodic agent wakes by evaluating schedules and delegating to AgentRunner. */
+/** Orchestrate periodic agent wakes. Evaluate schedules and delegate to AgentRunner. */
 export class Scheduler {
   #loadConfig;
   #stateManager;
@@ -209,7 +210,8 @@ export class Scheduler {
   }
 
   /**
-   * Reset any agents exceeding max runtime, reload config, then wake each agent whose schedule is due.
+   * Reset any agent that exceeds the maximum runtime. Reload the config. Then
+   * wake each agent whose schedule is due.
    */
   async wakeDueAgents() {
     const config = await this.#loadConfig();