@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/engine/process-tree.mjs

@@ -0,0 +1,551 @@
+/**
+ * lib/engine/process-tree.mjs — every process a shell started, including the
+ * ones that left its process group (CF-48, W5-B; CF-119).
+ *
+ * The engine starts each shell (background Bash, Monitor, a foreground Bash
+ * call, a hook command) in its own process group and signals the group. A
+ * process that calls setsid — `setsid cmd`, `perl -e 'POSIX::setsid()'`, node's
+ * `spawn(…, {detached:true})`, a daemonising server — is in a new session and
+ * group, so the group signal misses it and it outlives the engine. The tracker
+ * finds such processes three ways, and records each with its start identity:
+ *
+ *   1. the tree: every process reachable by parent links from the shell (while
+ *      the shell is still the process that was started) or from a process
+ *      already recorded, plus the members of the shell's own group;
+ *   2. the tag: the shell's environment carries COHORT_ENGINE_PROCESS_TAG=<random>,
+ *      which every descendant inherits unless it clears its environment. The
+ *      tracker records every process carrying the tag that started no earlier
+ *      than the shell (/proc/<pid>/environ on Linux; `ps -E` on macOS, which
+ *      shows the environment of the user's own processes except Apple platform
+ *      binaries), and every descendant of such a process;
+ *   3. samples: both readings are taken shortly after the shell starts (100 ms
+ *      and 500 ms), every 2 s while it runs, and again when it is stopped
+ *      (CF-119: the tag at every sample, not only at the stop). The records are
+ *      the ancestry map: a process recorded while it had a recorded parent, or
+ *      while it still carried the tag, is matched at the stop even after that
+ *      parent exited, it was reparented to pid 1, it called setsid and it
+ *      cleared its environment (`env -i`) — its start identity is what is
+ *      compared. Samples read the table asynchronously (the event loop is not
+ *      held by `ps`); the stop reads it synchronously.
+ *
+ * Identity: a process is recorded with its start time (`proc:<ticks>` from
+ * /proc/<pid>/stat, else `epoch:<seconds>` from `ps -o lstart=` under a fixed
+ * locale and time zone — the readings process-identity.mjs uses). A signal goes
+ * only to a recorded pid whose start time still matches, read again just before
+ * it is sent: a pid reused by another process is never signalled. A process
+ * whose start time cannot be read is never recorded.
+ *
+ * Stop: `signal(ids, 'SIGTERM')`, then `reap(ids, graceMs)` waits for the
+ * recorded processes to exit and SIGKILLs the ones still matching at the
+ * deadline — bounded. `killSync` (SIGKILL, for a process `exit` listener) does
+ * a synchronous capture and kill.
+ *
+ * Limits (a narrowing, not a boundary): a process that detaches (its parent
+ * exits or it calls setsid) AND clears its environment before any sample sees
+ * it — within ~100 ms of the shell's start, or between two samples — is not
+ * found; nor one whose ancestors all exited and that carried no visible tag at
+ * any sample, nor one that changes its own start identity. On macOS an Apple
+ * platform binary's environment is not readable, so its tag is invisible: a
+ * detached `/bin/sh -c 'sleep 5; exec env -i …'` whose parent exited at once is
+ * found by no sample (on Linux /proc shows its tag).
+ *
+ * `parsePsTable`, `parseProcStat`, `taggedPidsFromPs`, `descendantsOf` and
+ * `planSignals` are pure; the readers and `process.kill` are injectable.
+ *
+ * @module lib/engine/process-tree
+ */
+
+import { execFile, execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { readdirSync, readFileSync } from "node:fs";
+import { PS_PROBE_ENV, parseLstart, processStartToken, sameStartTime } from "./process-identity.mjs";
+
+export const PROCESS_TAG_ENV = "COHORT_ENGINE_PROCESS_TAG";
+/** Walks made after a shell starts (ms), then one every SAMPLE_INTERVAL_MS while it runs. */
+export const EARLY_SAMPLES_MS = Object.freeze([100, 500]);
+export const SAMPLE_INTERVAL_MS = 2_000;
+/** Recorded processes per shell, at most (a fork bomb must not grow the tracker without bound). */
+export const MAX_RECORDED_PER_ROOT = 1_024;
+const PROBE_TIMEOUT_MS = 3_000;
+const REAP_POLL_MS = 50;
+const PS_ROWS_ARGS = Object.freeze(["-A", "-o", "pid=,ppid=,pgid=,lstart="]);
+const PS_ENV_ARGS = Object.freeze(["-A", "-E", "-ww", "-o", "pid=,command="]);
+const ROWS_MAX_BUFFER = 16 * 1024 * 1024;
+const ENV_MAX_BUFFER = 64 * 1024 * 1024;
+
+/**
+ * @typedef {{pid:number, ppid:number, pgid:number, start:string|null}} ProcRow
+ * @typedef {{
+ *   rows?: () => ProcRow[],
+ *   taggedPids?: (tags:string[]) => Map<string, Set<number>>,
+ *   rowsAsync?: () => Promise<ProcRow[]>,
+ *   taggedPidsAsync?: (tags:string[]) => Promise<Map<string, Set<number>>>,
+ *   kill?: (pid:number, signal:NodeJS.Signals|0) => void,
+ *   selfPid?: number,
+ *   setTimer?: (fn:()=>void, ms:number) => any,
+ *   clearTimer?: (t:any) => void,
+ *   sample?: boolean,
+ *   now?: () => number,
+ * }} TrackerDeps
+ *   `rowsAsync` / `taggedPidsAsync`: the samples' readers; they default to the sync readers when those are injected
+ */
+
+/** @returns {string} a fresh tag for a child's environment */
+export function newProcessTag() {
+  return randomBytes(8).toString("hex");
+}
+
+/**
+ * `ps -A -o pid=,ppid=,pgid=,lstart=` output (under PS_PROBE_ENV) → rows. Pure.
+ * @param {string} text
+ * @returns {ProcRow[]}
+ */
+export function parsePsTable(text) {
+  /** @type {ProcRow[]} */
+  const rows = [];
+  for (const line of String(text ?? "").split("\n")) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*\S)\s*$/.exec(line);
+    if (!m) continue;
+    const epoch = parseLstart(m[4]);
+    rows.push({ pid: Number(m[1]), ppid: Number(m[2]), pgid: Number(m[3]), start: epoch === null ? null : `epoch:${epoch}` });
+  }
+  return rows;
+}
+
+/**
+ * One /proc/<pid>/stat line → a row. Pure. The command name (field 2) is in
+ * parentheses and may hold spaces and parentheses, so fields count from the last ")".
+ * @param {number} pid @param {string} stat
+ * @returns {ProcRow|null}
+ */
+export function parseProcStat(pid, stat) {
+  const s = String(stat ?? "");
+  const close = s.lastIndexOf(")");
+  if (close === -1) return null;
+  const f = s.slice(close + 2).split(" "); // f[0] = state (field 3)
+  const ppid = Number(f[1]);
+  const pgid = Number(f[2]);
+  if (!Number.isInteger(ppid) || !Number.isInteger(pgid)) return null;
+  const start = f[19];
+  return { pid, ppid, pgid, start: start && /^\d+$/.test(start) ? `proc:${start}` : null };
+}
+
+/**
+ * `ps -A -E -ww -o pid=,command=` output → the pids whose line carries each
+ * tag as `COHORT_ENGINE_PROCESS_TAG=<tag>`. Pure.
+ * @param {string} text @param {string[]} tags
+ * @returns {Map<string, Set<number>>}
+ */
+export function taggedPidsFromPs(text, tags) {
+  /** @type {Map<string, Set<number>>} */
+  const out = new Map(tags.map((t) => [t, new Set()]));
+  if (tags.length === 0) return out;
+  for (const line of String(text ?? "").split("\n")) {
+    if (!line.includes(PROCESS_TAG_ENV)) continue;
+    const m = /^\s*(\d+)\s/.exec(line);
+    if (!m) continue;
+    for (const t of tags) if (new RegExp(`(?:^|\\s)${PROCESS_TAG_ENV}=${t}(?:\\s|$)`).test(line)) out.get(t)?.add(Number(m[1]));
+  }
+  return out;
+}
+
+/**
+ * Every row reachable by parent links from `seeds`, plus every member of
+ * `groups`. Pure.
+ * @param {ProcRow[]} rows @param {Iterable<number>} seeds @param {Iterable<number>} [groups]
+ * @returns {ProcRow[]}
+ */
+export function descendantsOf(rows, seeds, groups = []) {
+  /** @type {Map<number, ProcRow[]>} */
+  const children = new Map();
+  for (const r of rows) {
+    if (r.pid === r.ppid) continue;
+    const list = children.get(r.ppid) ?? [];
+    list.push(r);
+    children.set(r.ppid, list);
+  }
+  const inGroups = new Set(groups);
+  const queue = [...seeds, ...rows.filter((r) => inGroups.has(r.pgid)).map((r) => r.pid)];
+  const seen = new Set();
+  while (queue.length > 0) {
+    const pid = /** @type number */ (queue.shift());
+    if (seen.has(pid)) continue;
+    seen.add(pid);
+    for (const c of children.get(pid) ?? []) queue.push(c.pid);
+  }
+  return rows.filter((r) => seen.has(r.pid));
+}
+
+/**
+ * Which recorded processes may be signalled now: those whose pid is present
+ * with the start time recorded for it. Never pid ≤ 1 or the engine itself. Pure.
+ * @param {Map<number, string>} recorded  pid → start
+ * @param {ProcRow[]} rows  a fresh reading
+ * @param {number} selfPid
+ * @returns {number[]}
+ */
+export function planSignals(recorded, rows, selfPid) {
+  const now = new Map(rows.map((r) => [r.pid, r.start]));
+  const out = [];
+  for (const [pid, start] of recorded) {
+    if (pid <= 1 || pid === selfPid) continue;
+    const live = now.get(pid);
+    if (live !== undefined && live !== null && sameStartTime(start, live) === true) out.push(pid);
+  }
+  return out;
+}
+
+/** @param {string|null} a @param {string|null} b  true when `a` started no earlier than `b` (same kind) */
+function startedNoEarlier(a, b) {
+  const pa = /^(proc|epoch):(\d+)$/.exec(String(a));
+  const pb = /^(proc|epoch):(\d+)$/.exec(String(b));
+  if (!pa || !pb || pa[1] !== pb[1]) return false;
+  const slack = pa[1] === "epoch" ? 1 : 0;
+  return Number(pa[2]) + slack >= Number(pb[2]);
+}
+
+/** @returns {ProcRow[]|null} the /proc table on Linux; null elsewhere or when /proc does not answer */
+function procRows() {
+  if (process.platform !== "linux") return null;
+  try {
+    /** @type {ProcRow[]} */
+    const rows = [];
+    for (const name of readdirSync("/proc")) {
+      if (!/^\d+$/.test(name)) continue;
+      try {
+        const row = parseProcStat(Number(name), readFileSync(`/proc/${name}/stat`, "utf8"));
+        if (row) rows.push(row);
+      } catch {
+        /* the process exited while the table was read */
+      }
+    }
+    return rows.length > 0 ? rows : null;
+  } catch {
+    return null; // no /proc: ask ps
+  }
+}
+
+/** @param {string[]} tags @returns {Map<string, Set<number>>|null} tagged pids from /proc on Linux; null elsewhere */
+function procTagged(tags) {
+  if (process.platform !== "linux") return null;
+  /** @type {Map<string, Set<number>>} */
+  const out = new Map(tags.map((t) => [t, new Set()]));
+  try {
+    for (const name of readdirSync("/proc")) {
+      if (!/^\d+$/.test(name)) continue;
+      let environ;
+      try {
+        environ = readFileSync(`/proc/${name}/environ`, "utf8");
+      } catch {
+        continue; // another user's process, or gone
+      }
+      for (const t of tags) if (environ.split("\0").includes(`${PROCESS_TAG_ENV}=${t}`)) out.get(t)?.add(Number(name));
+    }
+    return out;
+  } catch {
+    return null; // no /proc: ask ps
+  }
+}
+
+/** @param {readonly string[]} args @param {number} maxBuffer @returns {Promise<string|null>} */
+function psAsync(args, maxBuffer) {
+  return new Promise((resolve) => {
+    try {
+      execFile("ps", [...args], { encoding: "utf8", env: { ...PS_PROBE_ENV }, timeout: PROBE_TIMEOUT_MS, maxBuffer }, (err, stdout) => resolve(err ? null : String(stdout)));
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+/**
+ * The process table: /proc on Linux, else `ps`. [] when neither answers.
+ * @returns {ProcRow[]}
+ */
+export function readProcessRows() {
+  const fromProc = procRows();
+  if (fromProc) return fromProc;
+  try {
+    const out = execFileSync("ps", [...PS_ROWS_ARGS], { encoding: "utf8", env: { ...PS_PROBE_ENV }, stdio: ["ignore", "pipe", "ignore"], timeout: PROBE_TIMEOUT_MS, maxBuffer: ROWS_MAX_BUFFER });
+    return parsePsTable(out);
+  } catch {
+    return [];
+  }
+}
+
+/** {@link readProcessRows} without holding the event loop while `ps` runs. @returns {Promise<ProcRow[]>} */
+export async function readProcessRowsAsync() {
+  const fromProc = procRows();
+  if (fromProc) return fromProc;
+  const out = await psAsync(PS_ROWS_ARGS, ROWS_MAX_BUFFER);
+  return out === null ? [] : parsePsTable(out);
+}
+
+/**
+ * The pids carrying each tag in their environment.
+ * @param {string[]} tags
+ * @returns {Map<string, Set<number>>}
+ */
+export function readTaggedPids(tags) {
+  /** @type {Map<string, Set<number>>} */
+  const empty = new Map(tags.map((t) => [t, new Set()]));
+  if (tags.length === 0) return empty;
+  const fromProc = procTagged(tags);
+  if (fromProc) return fromProc;
+  try {
+    const text = execFileSync("ps", [...PS_ENV_ARGS], { encoding: "utf8", env: { ...PS_PROBE_ENV }, stdio: ["ignore", "pipe", "ignore"], timeout: PROBE_TIMEOUT_MS, maxBuffer: ENV_MAX_BUFFER });
+    return taggedPidsFromPs(text, tags);
+  } catch {
+    return empty;
+  }
+}
+
+/** {@link readTaggedPids} without holding the event loop while `ps` runs. @param {string[]} tags */
+export async function readTaggedPidsAsync(tags) {
+  /** @type {Map<string, Set<number>>} */
+  const empty = new Map(tags.map((t) => [t, new Set()]));
+  if (tags.length === 0) return empty;
+  const fromProc = procTagged(tags);
+  if (fromProc) return fromProc;
+  const text = await psAsync(PS_ENV_ARGS, ENV_MAX_BUFFER);
+  return text === null ? empty : taggedPidsFromPs(text, tags);
+}
+
+/**
+ * @typedef {{id:string, pid:number, tag:string|null, start:string|null, floor:string, recorded:Map<number,string>, active:boolean, timers:any[]}} TrackedRoot
+ *   `floor`: the shell's start time, or the wall clock when it was tracked (a lower bound for its descendants)
+ */
+
+/**
+ * @param {TrackerDeps} [deps]
+ */
+export function createProcessTracker(deps = {}) {
+  const rowsOf = deps.rows ?? readProcessRows;
+  const taggedOf = deps.taggedPids ?? readTaggedPids;
+  const rowsOfAsync = deps.rowsAsync ?? (deps.rows ? async () => rowsOf() : readProcessRowsAsync);
+  const taggedOfAsync = deps.taggedPidsAsync ?? (deps.taggedPids ? async (/** @type {string[]} */ t) => taggedOf(t) : readTaggedPidsAsync);
+  const kill = deps.kill ?? ((pid, sig) => process.kill(pid, sig));
+  const selfPid = deps.selfPid ?? process.pid;
+  const setTimer = deps.setTimer ?? setTimeout;
+  const clearTimer = deps.clearTimer ?? clearTimeout;
+  const sampling = deps.sample !== false;
+  const nowMs = deps.now ?? Date.now;
+  /** @type {Map<string, TrackedRoot>} */
+  const roots = new Map();
+  /** @type {any} */
+  let interval = null;
+
+  const record = (/** @type {TrackedRoot} */ root, /** @type {ProcRow} */ row) => {
+    if (row.start === null || row.pid <= 1 || row.pid === selfPid) return;
+    if (root.recorded.size >= MAX_RECORDED_PER_ROOT && !root.recorded.has(row.pid)) return;
+    root.recorded.set(row.pid, row.start);
+  };
+
+  /** @param {string[]|undefined} ids @returns {TrackedRoot[]} */
+  const rootsFor = (ids) => /** @type {TrackedRoot[]} */ ((ids ?? [...roots.keys()]).map((id) => roots.get(id)).filter((r) => r !== undefined));
+
+  /**
+   * Record into each root what one reading shows: its tree and, with `found`, its tagged processes.
+   * @param {TrackedRoot[]} list @param {ProcRow[]} rows @param {Map<string, Set<number>>|null} found
+   */
+  const apply = (list, rows, found) => {
+    const byPid = new Map(rows.map((r) => [r.pid, r]));
+    for (const root of list) {
+      const rootRow = byPid.get(root.pid);
+      if (root.start === null && rootRow && rootRow.start !== null && root.active) root.start = rootRow.start;
+      const rootIsOurs = rootRow !== undefined && root.start !== null && sameStartTime(root.start, rootRow.start) === true;
+      const seeds = [...(rootIsOurs ? [root.pid] : []), ...planSignals(root.recorded, rows, selfPid)];
+      for (const row of descendantsOf(rows, seeds, rootIsOurs ? [root.pid] : [])) record(root, row);
+    }
+    if (!found) return;
+    for (const root of list) {
+      if (root.tag === null) continue;
+      const pids = found.get(root.tag) ?? new Set();
+      const matched = rows.filter((r) => pids.has(r.pid) && startedNoEarlier(r.start, root.start ?? root.floor));
+      // A tagged process's own descendants that cleared the tag are found by the walk from it.
+      for (const row of descendantsOf(rows, matched.map((r) => r.pid))) record(root, row);
+    }
+  };
+
+  /**
+   * Walk the table for the given roots (all when omitted), synchronously; with `tags`, also record tagged processes.
+   * @param {string[]|undefined} ids @param {{tags?:boolean, rows?:ProcRow[]}} [o]
+   * @returns {ProcRow[]} the reading used
+   */
+  const capture = (ids, o = {}) => {
+    const list = rootsFor(ids);
+    if (list.length === 0) return o.rows ?? [];
+    const rows = o.rows ?? rowsOf();
+    const tags = o.tags ? list.filter((r) => r.tag !== null).map((r) => /** @type string */ (r.tag)) : [];
+    apply(list, rows, tags.length > 0 ? taggedOf(tags) : null);
+    return rows;
+  };
+
+  /** Roots waiting for the next asynchronous sample. @type {Set<string>} */
+  const queued = new Set();
+  /** @type {Promise<void>|null} */
+  let inFlight = null;
+  /**
+   * A sample (CF-119): the tree AND the tag, read without holding the event loop. Samples do not
+   * overlap; roots asked for meanwhile are taken by the next reading.
+   * @param {string[]} ids @returns {Promise<void>}
+   */
+  const sample = (ids) => {
+    for (const id of ids) queued.add(id);
+    if (inFlight) return inFlight;
+    const run = async () => {
+      while (queued.size > 0) {
+        const list = rootsFor([...queued]).filter((r) => r.active);
+        queued.clear();
+        if (list.length === 0) continue;
+        try {
+          const rows = await rowsOfAsync();
+          const tags = list.filter((r) => r.tag !== null).map((r) => /** @type string */ (r.tag));
+          const found = tags.length > 0 ? await taggedOfAsync(tags) : null;
+          // A root forgotten while the reading ran is not recorded into.
+          apply(list.filter((r) => roots.get(r.id) === r), rows, found);
+        } catch {
+          /* a failed sample: the stop still captures */
+        }
+      }
+    };
+    inFlight = run().finally(() => {
+      inFlight = null;
+    });
+    return inFlight;
+  };
+
+  const ensureInterval = () => {
+    if (!sampling || interval !== null) return;
+    interval = setInterval(() => {
+      const active = [...roots.values()].filter((r) => r.active).map((r) => r.id);
+      if (active.length === 0) {
+        clearInterval(interval);
+        interval = null;
+        return;
+      }
+      void sample(active);
+    }, SAMPLE_INTERVAL_MS);
+    interval.unref?.();
+  };
+
+  return {
+    /**
+     * Track a process started with `env[PROCESS_TAG_ENV] = tag` (tag may be null).
+     * @param {{id:string, pid:number, tag?:string|null, start?:string|null}} p
+     */
+    track({ id, pid, tag = null, start = null }) {
+      // The shell's start time: read from /proc where that costs no subprocess; elsewhere the first
+      // walk reads it. `floor` bounds a tagged process's start even if no walk ran before the shell exited.
+      let known = start;
+      if (known === null && process.platform === "linux" && !deps.rows) known = processStartToken(pid);
+      /** @type {TrackedRoot} */
+      const root = { id, pid, tag, start: known, floor: known ?? `epoch:${Math.floor(nowMs() / 1000)}`, recorded: new Map(), active: true, timers: [] };
+      roots.set(id, root);
+      if (sampling) {
+        for (const ms of EARLY_SAMPLES_MS) {
+          const t = setTimer(() => {
+            if (roots.get(id) === root && root.active) void sample([id]);
+          }, ms);
+          t?.unref?.();
+          root.timers.push(t);
+        }
+        ensureInterval();
+      }
+    },
+
+    /** The root process has exited on its own: stop sampling it (its records are kept). @param {string} id */
+    rootExited(id) {
+      const root = roots.get(id);
+      if (!root) return;
+      root.active = false;
+      for (const t of root.timers) clearTimer(t);
+    },
+
+    capture,
+
+    /** Take a sample now (tests; the timers call it). @param {string[]} [ids] */
+    sample: (/** @type {string[]|undefined} */ ids) => sample(ids ?? [...roots.keys()]),
+
+    /**
+     * Signal every recorded process of these roots whose identity still matches.
+     * @param {string[]} ids @param {NodeJS.Signals} sig
+     * @returns {number[]} the pids signalled
+     */
+    signal(ids, sig) {
+      const rows = rowsOf();
+      const sent = [];
+      for (const id of ids) {
+        const root = roots.get(id);
+        if (!root) continue;
+        for (const pid of planSignals(root.recorded, rows, selfPid)) {
+          try {
+            kill(pid, sig);
+            sent.push(pid);
+          } catch {
+            /* exited meanwhile, or not ours to signal */
+          }
+        }
+      }
+      return sent;
+    },
+
+    /**
+     * Wait up to `graceMs` for the recorded processes of these roots to exit; SIGKILL the
+     * ones still matching at the deadline. Bounded: graceMs plus one reading.
+     * @param {string[]} ids @param {number} graceMs
+     * @returns {Promise<number[]>} the pids that needed SIGKILL
+     */
+    async reap(ids, graceMs) {
+      const end = Date.now() + Math.max(0, graceMs);
+      const pending = () => {
+        const rows = rowsOf();
+        return ids.flatMap((id) => {
+          const root = roots.get(id);
+          return root ? planSignals(root.recorded, rows, selfPid) : [];
+        });
+      };
+      let left = pending();
+      while (left.length > 0 && Date.now() < end) {
+        // Not unref'd: the wait is bounded, and a caller awaiting it must keep the event loop alive.
+        await new Promise((r) => setTimer(r, Math.min(REAP_POLL_MS, Math.max(1, end - Date.now()))));
+        left = pending();
+      }
+      return left.length > 0 ? this.signal(ids, "SIGKILL") : [];
+    },
+
+    /**
+     * For a process `exit` listener: capture (with tags) and SIGKILL, synchronously.
+     * @param {string[]} [ids]
+     */
+    killSync(ids) {
+      const list = ids ?? [...roots.keys()];
+      try {
+        capture(list, { tags: true });
+        this.signal(list, "SIGKILL");
+      } catch {
+        /* best effort at exit */
+      }
+    },
+
+    /** @param {string} id */
+    recorded(id) {
+      return new Map(roots.get(id)?.recorded ?? []);
+    },
+
+    /** Stop tracking a root. @param {string} id */
+    forget(id) {
+      const root = roots.get(id);
+      if (!root) return;
+      for (const t of root.timers) clearTimer(t);
+      roots.delete(id);
+    },
+
+    /** Stop every timer. */
+    dispose() {
+      for (const r of roots.values()) for (const t of r.timers) clearTimer(t);
+      if (interval !== null) clearInterval(interval);
+      interval = null;
+    },
+  };
+}

package/lib/engine/prompt.mjs

@@ -0,0 +1,60 @@
+/**
+ * lib/engine/prompt.mjs — the engine's base system prompt (pure).
+ *
+ * Authorship: written for Cohort Engine by the Cohort team, 2026-09-14. It is
+ * original text; see docs/engine/clean-room.md for what may and may not inform
+ * it.
+ *
+ * Kept short on purpose: every token here is paid on every turn of every run,
+ * and is the head of the prompt-cache prefix. Anything that varies per run
+ * goes at the END (environment, then the caller's appended prompt), so the
+ * stable part stays byte-identical across runs and caches.
+ *
+ * @module lib/engine/prompt
+ */
+
+export const BASE_PROMPT = `You are a software agent working in a directory on a computer, through the tools you are given. Carry the task through to a result, then give a short final answer.
+
+How to work:
+- Look before you change anything. Read a file before you Edit or Write it.
+- Use Edit for targeted changes and Write for new files or complete rewrites.
+- Find things with Glob (file names) and Grep (contents) instead of guessing paths. Use absolute paths.
+- Use Bash for anything the other tools do not cover. Commands cannot prompt for input.
+- When several read-only lookups are independent, request them in the same reply; they run together.
+- When a tool returns an error, read it and change your approach. Repeating an identical call returns the same result.
+- Report what you actually observed. If you could not finish, say what stopped you.`;
+
+/**
+ * @param {object} p
+ * @param {string} p.cwd
+ * @param {string} p.platform
+ * @param {string} p.date          YYYY-MM-DD (day granularity keeps the cache warm all day)
+ * @param {string[]} p.toolNames
+ * @param {string|null} [p.systemPrompt]  replaces BASE_PROMPT entirely
+ * @param {string|null} [p.append]        appended after the environment block
+ * @param {string|null} [p.instructions]  CLAUDE.md / COHORT.md / AGENTS.md block (context/instructions.mjs)
+ * @param {string|null} [p.skills]        the skill listing (skills/index.mjs)
+ * @param {string|null} [p.notes]         engine notes fixed for the run (e.g. deferred tools)
+ *
+ * Order: base prompt, instructions, skills, notes, environment, appended
+ * text. The first four change only when files or configuration change, so
+ * they stay in the cached prefix; the environment carries the date and
+ * follows them. Nothing is added to the system prompt after a run starts.
+ */
+export function buildSystemPrompt({ cwd, platform, date, toolNames, systemPrompt = null, append = null, instructions = null, skills = null, notes = null }) {
+  const parts = [systemPrompt ?? BASE_PROMPT];
+  if (instructions) parts.push(instructions);
+  if (skills) parts.push(skills);
+  if (notes) parts.push(notes);
+  parts.push(
+    [
+      "Environment:",
+      `- Working directory: ${cwd}`,
+      `- Platform: ${platform}`,
+      `- Date: ${date}`,
+      `- Tools: ${toolNames.length > 0 ? toolNames.join(", ") : "none"}`,
+    ].join("\n"),
+  );
+  if (append) parts.push(append);
+  return parts.join("\n\n");
+}