@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/engine/process-identity.mjs

@@ -0,0 +1,164 @@
+/**
+ * lib/engine/process-identity.mjs — who wrote a record, and whether that
+ * process is still the one running (W4-E2 review: a bare PID is not enough).
+ *
+ * Task states (agents/persist.mjs) and workflow journals (workflow/journal.mjs)
+ * record the process that runs them, so that after a restart a record left
+ * "running" can be judged: still running somewhere, or cut off. A PID alone
+ * gets two cases wrong:
+ *
+ *   · the SAME PID as this process — a container restart where the engine is
+ *     pid 1 again, or a host that rebuilds a runtime inside one process. The
+ *     record's writer is not necessarily this process;
+ *   · a LIVE process holding the recorded PID after a reboot or PID wraparound.
+ *     `kill(pid, 0)` succeeds, but it is some other program.
+ *
+ * So a record carries three things: the PID, `nonce` (random, fixed for the
+ * life of this process) and `startToken` (the OS's start time for that PID,
+ * when it can be read). This module is the one implementation of that reading;
+ * the W4-E1 session lock (session/store.mjs) records and compares its holder's
+ * start time with it too: `proc:<ticks>` from
+ * `/proc/<pid>/stat` on Linux; elsewhere `epoch:<seconds>` from
+ * `ps -o lstart= -p <pid>` run under a fixed `PATH=/bin:/usr/bin LC_ALL=C
+ * TZ=UTC0` and parsed to a number, so a record written by a launchd daemon and
+ * read from a terminal in another locale or time zone agree.
+ *
+ * `judgeOwner`, `parseLstart` and `sameStartTime` are pure; the probes are the
+ * only I/O and are injectable.
+ *
+ * @module lib/engine/process-identity
+ */
+
+import { execFileSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+/** Random for each engine process; a record with another nonce was not written by this process. */
+export const PROCESS_NONCE = randomBytes(8).toString("hex");
+
+/**
+ * The environment `ps` runs in: fixed, so the answer does not depend on the
+ * caller's locale or time zone (`ps -o lstart=` prints local time in the
+ * caller's locale).
+ */
+export const PS_PROBE_ENV = Object.freeze({ PATH: "/bin:/usr/bin", LC_ALL: "C", TZ: "UTC0" });
+
+/** How far apart two `epoch:` readings of one process's start time may be (seconds). */
+export const START_TIME_TOLERANCE_S = 1;
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+
+/** @param {number} pid */
+export function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return /** @type any */ (e)?.code === "EPERM";
+  }
+}
+
+/**
+ * Parse `ps -o lstart=` output, printed under {@link PS_PROBE_ENV} (UTC), to
+ * epoch seconds. Either day/month order. Pure. null when unparseable.
+ * @param {string} text
+ * @returns {number|null}
+ */
+export function parseLstart(text) {
+  const t = String(text || "").trim();
+  const time = t.match(/\b(\d{1,2}):(\d{2}):(\d{2})\b/);
+  const year = t.match(/\b(\d{4})\b/);
+  const month = t.match(/\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\b/i);
+  const day = t.replace(time ? time[0] : "", "").replace(year ? year[0] : "", "").match(/\b(\d{1,2})\b/);
+  if (!time || !year || !month || !day) return null;
+  const ms = Date.UTC(Number(year[1]), MONTHS.indexOf(month[1].toLowerCase()), Number(day[1]), Number(time[1]), Number(time[2]), Number(time[3]));
+  return Number.isFinite(ms) ? Math.floor(ms / 1000) : null;
+}
+
+/** This process's own token, read once it has been read successfully. @type {string|null} */
+let selfToken = null;
+
+/**
+ * When the process now holding `pid` started, as a tagged value: equal (within
+ * {@link START_TIME_TOLERANCE_S} for `epoch:`) for the same process, different
+ * for a later process that reuses the PID, whoever asks. null when it cannot
+ * be read (no such process, a failed probe, a platform with no answer).
+ * @param {number} pid
+ * @param {{readFileSync?:(p:string, enc:"utf8")=>string, execFileSync?:(file:string, args:string[], o:any)=>string|Buffer}} [deps]
+ * @returns {string|null}
+ */
+export function processStartToken(pid, deps = {}) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  const cacheable = pid === process.pid && !deps.readFileSync && !deps.execFileSync;
+  if (cacheable && selfToken !== null) return selfToken;
+  const read = deps.readFileSync ?? readFileSync;
+  const exec = deps.execFileSync ?? execFileSync;
+  /** @type {string|null} */
+  let token = null;
+  try {
+    // /proc/<pid>/stat: field 22 is the start time in clock ticks since boot. The command name
+    // (field 2) is parenthesised and may contain spaces and parens, so count from the last ")".
+    const stat = read(`/proc/${pid}/stat`, "utf8");
+    const start = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
+    if (start && /^\d+$/.test(start)) token = `proc:${start}`;
+  } catch {
+    /* no /proc (macOS), or the process is gone: ask ps */
+  }
+  if (token === null) {
+    try {
+      const out = String(exec("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", env: { ...PS_PROBE_ENV }, stdio: ["ignore", "pipe", "ignore"], timeout: 2_000 })).trim();
+      const epoch = out ? parseLstart(out) : null;
+      token = epoch === null ? null : `epoch:${epoch}`;
+    } catch {
+      token = null; // ps exits 1 for a pid that is not running
+    }
+  }
+  if (cacheable && token !== null) selfToken = token;
+  return token;
+}
+
+/**
+ * Do two start-time readings name the same process? Pure. `proc:` values
+ * match exactly, `epoch:` values within {@link START_TIME_TOLERANCE_S}.
+ * Readings of different kinds, or unrecognised ones, cannot be compared: null.
+ * @param {unknown} a @param {unknown} b
+ * @returns {boolean|null}
+ */
+export function sameStartTime(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 null;
+  if (pa[1] === "proc") return pa[2] === pb[2];
+  return Math.abs(Number(pa[2]) - Number(pb[2])) <= START_TIME_TOLERANCE_S;
+}
+
+/**
+ * @typedef {Object} RecordedOwner  what a record says about the process that ran it
+ * @property {number} pid
+ * @property {string|null} [nonce]
+ * @property {string|null} [startToken]
+ */
+
+/**
+ * Is the process that wrote a record this one, another live one, or gone? Pure.
+ *
+ *   same PID, same nonce          → 'self'  (this process; the caller checks whether it still holds the work)
+ *   same PID, other or no nonce   → 'dead'  (this process holds that PID now, so the writer is gone)
+ *   other PID, not alive          → 'dead'
+ *   other PID, alive, both start times known, comparable and different → 'dead' (the PID was reused)
+ *   other PID, alive otherwise    → 'alive' (no start time to compare: the PID check stands)
+ *
+ * @param {RecordedOwner} owner
+ * @param {{pid:number, nonce:string}} self
+ * @param {{isAlive:(pid:number)=>boolean, startToken:(pid:number)=>string|null}} probe
+ * @returns {'self'|'alive'|'dead'}
+ */
+export function judgeOwner(owner, self, probe) {
+  if (owner.pid === self.pid) return typeof owner.nonce === "string" && owner.nonce === self.nonce ? "self" : "dead";
+  if (!probe.isAlive(owner.pid)) return "dead";
+  if (typeof owner.startToken === "string") {
+    const live = probe.startToken(owner.pid);
+    if (live !== null && sameStartTime(owner.startToken, live) === false) return "dead";
+  }
+  return "alive";
+}