harnery 0.45.0 → 0.45.2

package/dist/core/agents/state/proc-start.js

@@ -33,7 +33,6 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { coordEnv } from "../../../lib/env.js";
-import { signalProcessWithHandle, windowsProcessStartToken } from "./process-handle.js";
 /**
  * The `ps` probe is text formatted by `strftime("%c", localtime(...))`, so its
  * output moves with `TZ` and `LC_TIME`. A hook running under `LC_ALL=C` (git
@@ -55,8 +54,6 @@ export function startTokenProbe() {
     const override = coordEnv("PID_PROBE");
     if (override === "procfs" || override === "ps")
         return override;
-    if (process.platform === "win32")
-        return "windows";
     if (cachedProbe === undefined) {
         cachedProbe = existsSync("/proc/self/stat") ? "procfs" : "ps";
     }
@@ -98,7 +95,7 @@ export function resetStartTokenCaches() {
  * than by splitting the whole line, because comm is the executable name in
  * parentheses and may itself contain spaces and parens. The boot segment is
  * dropped rather than faked when the kernel will not name its boot, which
- * yields the pre-boot-id shape that `tokensAgree` still accepts.
+ * yields the pre-boot-id shape that `verifyProcessGeneration` compares by ticks.
  */
 export function procfsStartToken(pid) {
     let stat;
@@ -152,93 +149,63 @@ function defaultPsRun(pid) {
 export function processStartToken(pid) {
     if (!Number.isFinite(pid) || pid <= 0)
         return null;
-    const probe = startTokenProbe();
-    return probe === "windows"
-        ? windowsProcessStartToken(pid)
-        : probe === "procfs"
-            ? procfsStartToken(pid)
-            : psStartToken(pid);
+    return startTokenProbe() === "procfs" ? procfsStartToken(pid) : psStartToken(pid);
 }
-/** A missing or unreadable token never establishes process identity. */
+/**
+ * Does `pid` still name the run that wrote `recordedToken`?
+ *
+ * - `"same"`: both tokens present and equal.
+ * - `"different"`: the pid was recycled. A liveness check cannot see this,
+ *   because a recycled pid is alive.
+ * - `"unknown"`: a token is missing, malformed, or unreadable. Never treat
+ *   this as proof of identity.
+ *
+ * A Linux token written without a boot segment cannot identify a run across
+ * reboots, so it is compared on its tick count: a different count proves a
+ * different run, and an equal count stays unknown.
+ */
 export function verifyProcessGeneration(pid, recordedToken, readToken = processStartToken) {
     if (!Number.isInteger(pid) ||
         pid <= 0 ||
         typeof recordedToken !== "string" ||
         !recordedToken.trim())
         return "unknown";
-    // A bootless Linux token cannot identify a process across machine boots.
-    if (/^l\d+$/.test(recordedToken))
-        return "unknown";
+    let currentToken;
     try {
-        const currentToken = readToken(pid);
-        if (typeof currentToken !== "string" || !currentToken.trim())
-            return "unknown";
-        if (/^l\d+$/.test(currentToken))
-            return "unknown";
-        return currentToken === recordedToken ? "same" : "different";
+        currentToken = readToken(pid);
     }
     catch {
         return "unknown";
     }
+    if (typeof currentToken !== "string" || !currentToken.trim())
+        return "unknown";
+    const bootless = (token) => /^l\d+$/.test(token);
+    if (recordedToken[0] === "l" &&
+        currentToken[0] === "l" &&
+        (bootless(recordedToken) || bootless(currentToken)))
+        return ticksOf(recordedToken) === ticksOf(currentToken) ? "unknown" : "different";
+    return currentToken === recordedToken ? "same" : "different";
+}
+function ticksOf(token) {
+    const dot = token.indexOf(".");
+    return dot === -1 ? token.slice(1) : token.slice(dot + 1);
 }
 /**
- * Observations may refuse a signal, but only the retained native process handle
- * can authorize it. No numeric-PID effect follows the preliminary token read.
+ * Recheck the process generation immediately before sending the signal.
+ *
+ * The process can still exit and its PID can be reused between the token read
+ * and the signal. Eliminating that race requires a generation-bound OS handle.
  */
 export function signalIfSameGeneration(pid, recordedToken, signal, dependencies = {}) {
+    const kill = dependencies.kill ?? process.kill;
     const verdict = verifyProcessGeneration(pid, recordedToken, dependencies.readToken);
     if (verdict !== "same")
         return { sent: false, verdict };
     try {
-        return (dependencies.signalProcess ?? signalProcessWithHandle)(pid, recordedToken, signal);
+        kill(pid, signal);
+        return { sent: true, verdict };
     }
     catch {
-        return { sent: false, verdict: "unknown" };
+        return { sent: false, verdict };
     }
 }
-/**
- * Do two tokens describe the same run?
- *
- * Equality, plus one concession: a row written before tokens carried a boot
- * segment recorded the tick count alone, so it is compared on the part it
- * actually recorded. Refusing that would call every pre-upgrade row a recycled
- * pid and prune a working machine's live rows the first time the new code ran.
- * Such a row loses its reboot protection until the next write rewrites it,
- * which is a strictly better position than the one it came from.
- */
-export function tokensAgree(recorded, current) {
-    if (recorded === current)
-        return true;
-    // Only the Linux form has a boot segment to disagree about, and only when
-    // exactly one side carries one is this a shape difference rather than two
-    // genuinely different start instants.
-    if (recorded[0] !== "l" || current[0] !== "l")
-        return false;
-    if (recorded.includes(".") === current.includes("."))
-        return false;
-    return ticksOf(recorded) === ticksOf(current);
-}
-function ticksOf(token) {
-    const dot = token.indexOf(".");
-    return dot === -1 ? token.slice(1) : token.slice(dot + 1);
-}
-/**
- * Does `pid` still name the process a row recorded?
- *
- * Three answers, and the difference between the last two matters:
- *
- * - `"match"` — recorded token, current token, same run. The row is trustworthy.
- * - `"mismatch"` — both present and different. The pid was recycled. This is
- *   the case a liveness check cannot see, because a recycled pid is alive.
- * - `"unverified"` — no recorded token (a row written before tokens existed) or
- *   no current one (an unsupported platform). Callers treat this the way they
- *   treated every row previously: trust it if the pid is alive.
- */
-export function checkPidToken(pid, recorded) {
-    if (!recorded)
-        return "unverified";
-    const current = processStartToken(pid);
-    if (!current)
-        return "unverified";
-    return tokensAgree(recorded, current) ? "match" : "mismatch";
-}

package/dist/core/agents/state/service-process.d.ts

@@ -0,0 +1,61 @@
+import { type ProcessGenerationSignalDependencies, type ProcessGenerationVerdict } from "./proc-start.js";
+export interface ServiceProcessDependencies extends ProcessGenerationSignalDependencies {
+    /** Throws ESRCH, or returns false, when the process is gone. */
+    probePid?: (pid: number) => unknown;
+}
+export type ServiceLiveness = "running" | "stopped" | "unknown";
+export interface ServiceProcessOwner {
+    pid: number;
+    host: string;
+    start_token?: string;
+    state?: string;
+}
+/**
+ * A stale heartbeat does not prove that a process has exited. Another host, a
+ * probe error other than ESRCH, or an unverifiable token answers unknown. A
+ * recorded `stopped` state counts only while the generation still matches.
+ */
+export declare function observeServiceProcess(owner: ServiceProcessOwner, dependencies?: ServiceProcessDependencies): {
+    generation: ProcessGenerationVerdict;
+    liveness: ServiceLiveness;
+};
+/** Refuse a start while another owner runs or cannot be identified. */
+export declare function serviceStartRefusal(label: string, stopCommand: string, pid: number | undefined, liveness: ServiceLiveness): Error;
+export interface ServiceLease {
+    pid: number;
+    start_token?: string;
+    host: string;
+    nonce: string;
+    created_at?: string;
+}
+export declare function readServiceLease(path: string): ServiceLease | undefined;
+/** An absent lease is stopped; an unreadable one cannot be identified. */
+export declare function serviceLeaseOwner(path: string): {
+    lease?: ServiceLease;
+    liveness: ServiceLiveness;
+};
+/**
+ * Take the singleton lease with an exclusive create. A lease whose owner is
+ * proven stopped is replaced; any other owner refuses the start.
+ */
+export declare function acquireServiceLease(path: string, refuse: (pid: number | undefined, liveness: ServiceLiveness) => Error, fields?: Record<string, unknown>): {
+    nonce: string;
+    release: () => void;
+};
+export interface ServiceStopFields {
+    signal_sent: boolean;
+    signal_verdict: ProcessGenerationVerdict;
+}
+/**
+ * Write the durable stop request, then SIGTERM the owner `status` observed as
+ * running on this host, after a fresh generation check. The request stays for
+ * the daemon either way; `read` reports the state afterward.
+ */
+export declare function requestServiceStop<S extends {
+    liveness: ServiceLiveness;
+    generation: ProcessGenerationVerdict;
+    record?: ServiceProcessOwner;
+}>(status: S, read: () => S, stopPath: string, dependencies?: ServiceProcessDependencies, options?: {
+    signal?: boolean;
+}): S & ServiceStopFields;
+//# sourceMappingURL=service-process.d.ts.map

package/dist/core/agents/state/service-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-process.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/service-process.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,KAAK,mCAAmC,EACxC,KAAK,wBAAwB,EAI9B,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,0BAA2B,SAAQ,mCAAmC;IACrF,gEAAgE;IAChE,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACrC;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,EAC1B,YAAY,GAAE,0BAA+B,GAC5C;IAAE,UAAU,EAAE,wBAAwB,CAAC;IAAC,QAAQ,EAAE,eAAe,CAAA;CAAE,CAuBrE;AAED,uEAAuE;AACvE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,eAAe,GACxB,KAAK,CAMP;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAmBvE;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;IAC/C,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;CAC3B,CAIA;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,eAAe,KAAK,KAAK,EACrE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CA0CxC;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,wBAAwB,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,SAAS;IACR,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,wBAAwB,CAAC;IACrC,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B,EAED,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,MAAM,CAAC,EACb,QAAQ,EAAE,MAAM,EAChB,YAAY,GAAE,0BAA+B,EAC7C,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,CAAC,GAAG,iBAAiB,CAevB"}

package/dist/core/agents/state/service-process.js

@@ -0,0 +1,143 @@
+/**
+ * One owner check for every singleton background service (governor, local
+ * supervisor, legacy resource observer): is the recorded process still the
+ * run that wrote the record, and how is a stop requested?
+ */
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+import { writePrivateJsonAtomic } from "../../storage/atomic-json.js";
+import { stateDirMode, stateFileMode } from "../../storage/modes.js";
+import { processStartToken, signalIfSameGeneration, verifyProcessGeneration, } from "./proc-start.js";
+/**
+ * A stale heartbeat does not prove that a process has exited. Another host, a
+ * probe error other than ESRCH, or an unverifiable token answers unknown. A
+ * recorded `stopped` state counts only while the generation still matches.
+ */
+export function observeServiceProcess(owner, dependencies = {}) {
+    if (owner.host !== hostname())
+        return { generation: "unknown", liveness: "unknown" };
+    try {
+        if ((dependencies.probePid ?? ((pid) => process.kill(pid, 0)))(owner.pid) === false)
+            return { generation: "unknown", liveness: "stopped" };
+    }
+    catch (error) {
+        return {
+            generation: "unknown",
+            liveness: error.code === "ESRCH" ? "stopped" : "unknown",
+        };
+    }
+    const generation = verifyProcessGeneration(owner.pid, owner.start_token, dependencies.readToken);
+    return {
+        generation,
+        liveness: generation === "same"
+            ? owner.state === "stopped"
+                ? "stopped"
+                : "running"
+            : generation === "different"
+                ? "stopped"
+                : "unknown",
+    };
+}
+/** Refuse a start while another owner runs or cannot be identified. */
+export function serviceStartRefusal(label, stopCommand, pid, liveness) {
+    return new Error(liveness === "running"
+        ? `${label} is already running under pid ${pid}`
+        : `${label} process generation is unknown${pid ? ` for pid ${pid}` : ""}; run \`${stopCommand}\` to write a durable stop request before starting it again`);
+}
+export function readServiceLease(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (!Number.isSafeInteger(value.pid) ||
+            (value.pid ?? 0) <= 0 ||
+            typeof value.host !== "string" ||
+            !value.host ||
+            typeof value.nonce !== "string" ||
+            !value.nonce)
+            return undefined;
+        return {
+            ...value,
+            start_token: typeof value.start_token === "string" ? value.start_token : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** An absent lease is stopped; an unreadable one cannot be identified. */
+export function serviceLeaseOwner(path) {
+    if (!existsSync(path))
+        return { liveness: "stopped" };
+    const lease = readServiceLease(path);
+    return { lease, liveness: lease ? observeServiceProcess(lease).liveness : "unknown" };
+}
+/**
+ * Take the singleton lease with an exclusive create. A lease whose owner is
+ * proven stopped is replaced; any other owner refuses the start.
+ */
+export function acquireServiceLease(path, refuse, fields = {}) {
+    mkdirSync(dirname(path), { recursive: true, mode: stateDirMode() });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const startToken = processStartToken(process.pid);
+        const lease = {
+            ...fields,
+            pid: process.pid,
+            ...(startToken ? { start_token: startToken } : {}),
+            host: hostname(),
+            nonce: randomUUID(),
+            created_at: new Date().toISOString(),
+        };
+        try {
+            const fd = openSync(path, "wx", stateFileMode());
+            try {
+                writeFileSync(fd, `${JSON.stringify(lease)}\n`, "utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+            return {
+                nonce: lease.nonce,
+                release: () => {
+                    if (readServiceLease(path)?.nonce !== lease.nonce)
+                        return;
+                    try {
+                        unlinkSync(path);
+                    }
+                    catch {
+                        // A missing lease is already released.
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const owner = serviceLeaseOwner(path);
+            if (owner.liveness !== "stopped")
+                throw refuse(owner.lease?.pid, owner.liveness);
+            try {
+                unlinkSync(path);
+            }
+            catch {
+                // A concurrent starter may have replaced or removed the stale lease.
+            }
+        }
+    }
+    throw new Error(`could not acquire the singleton lease at ${path}`);
+}
+/**
+ * Write the durable stop request, then SIGTERM the owner `status` observed as
+ * running on this host, after a fresh generation check. The request stays for
+ * the daemon either way; `read` reports the state afterward.
+ */
+export function requestServiceStop(status, read, stopPath, dependencies = {}, options = {}) {
+    writePrivateJsonAtomic(stopPath, {
+        requested_at: new Date().toISOString(),
+        requested_by_pid: process.pid,
+    });
+    const signal = options.signal !== false && status.liveness === "running" && status.record?.host === hostname()
+        ? signalIfSameGeneration(status.record.pid, status.record.start_token, "SIGTERM", dependencies)
+        : { sent: false, verdict: status.generation };
+    return { ...read(), signal_sent: signal.sent, signal_verdict: signal.verdict };
+}

package/dist/core/agents/state/stale-sweep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stale-sweep.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/stale-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyIH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;IAC7C,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAuPA"}
+{"version":3,"file":"stale-sweep.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/stale-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkEH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG;IAC7C,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;CAC/B,CAyJA"}