@diffexai/diffex 0.3.0 → 0.3.2

package/dist/utils/owned-shell-processes.js

@@ -1,61 +1,171 @@
-import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, mkdirSync, openSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { killProcessTree, trackDetachedChildPid, untrackDetachedChildPid } from "./shell.js";
-function isAlive(pid) {
-    try {
-        process.kill(process.platform === "win32" ? pid : -pid, 0);
-        return true;
-    }
-    catch (error) {
-        if (error.code === "ESRCH")
-            return false;
-        if (error.code === "EPERM")
-            return true;
-        throw error;
-    }
-}
-/** A session owns the process groups it launches, including background jobs. */
+import { hasShellExecutionToken, readShellProcessGroup } from "./shell-process-identity.js";
+/** Session ownership ends only after a successful, durably published handoff. */
 export class OwnedShellProcesses {
-    #pids = new Set();
-    track(pid) {
-        this.#pids.add(pid);
-        trackDetachedChildPid(pid);
+    policy;
+    #executions = new Map();
+    constructor(policy = { lifetime: "session" }) {
+        if (policy.lifetime !== "session" && policy.lifetime !== "environment") {
+            throw new Error("Invalid background process lifetime");
+        }
+        if (policy.lifetime === "environment") {
+            if (process.platform !== "linux" && process.platform !== "darwin") {
+                throw new Error("Environment background process ownership requires Linux or macOS");
+            }
+            if (!policy.ownershipDirectory || !isAbsolute(policy.ownershipDirectory)) {
+                throw new Error("Environment background process ownership requires an absolute ownershipDirectory");
+            }
+            mkdirSync(policy.ownershipDirectory, { recursive: true, mode: 0o700 });
+        }
+        this.policy = Object.freeze({ ...policy });
+    }
+    track(pid, executionId) {
+        const execution = { id: executionId, state: "active", members: [] };
+        this.#executions.set(pid, execution);
+        trackDetachedChildPid(pid, () => this.terminate(pid));
+        try {
+            execution.members = process.platform === "win32" ? [] : readShellProcessGroup(pid);
+            this.#publish(pid, execution, "session", "active");
+        }
+        catch (error) {
+            this.terminate(pid);
+            throw error;
+        }
+    }
+    /** Called synchronously on shell exit, before output draining or another event can cancel it. */
+    complete(pid, successful) {
+        const execution = this.#executions.get(pid);
+        if (!execution || execution.state !== "active")
+            return;
+        // This callback belongs to the ChildProcess just reaped by Node. Capture the
+        // surviving group now; later cleanup must validate these process identities.
+        execution.members = process.platform === "win32" ? [] : readShellProcessGroup(pid);
+        execution.state = "background";
+        if (!successful || this.policy.lifetime === "session")
+            return;
+        const members = this.#members(pid, execution);
+        if (members.length === 0) {
+            this.releaseIfExited(pid);
+            return;
+        }
+        execution.members = members;
+        // No await between publication and removing both cleanup registrations.
+        // Atomic rename is the ownership commit point, including after a forced CLI death.
+        this.#publish(pid, execution, "environment", "background");
+        this.#executions.delete(pid);
+        untrackDetachedChildPid(pid);
+    }
+    #publish(pid, execution, owner, state) {
+        if (this.policy.lifetime !== "environment")
+            return;
+        const record = {
+            version: 1,
+            executionId: execution.id,
+            owner,
+            state,
+            processGroupId: pid,
+            supervisorPid: process.pid,
+            members: execution.members,
+        };
+        const path = join(this.policy.ownershipDirectory, `${execution.id}.json`);
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        const fd = openSync(temporary, "wx", 0o600);
+        try {
+            try {
+                writeFileSync(fd, `${JSON.stringify(record)}\n`);
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            renameSync(temporary, path);
+        }
+        finally {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { }
+        }
+    }
+    #members(pid, execution) {
+        const members = readShellProcessGroup(pid);
+        if (members.length === 0)
+            return [];
+        const known = members.some((member) => execution.members.some((previous) => previous.pid === member.pid && previous.startTime === member.startTime));
+        if (!known && !members.some((member) => hasShellExecutionToken(member.pid, execution.id))) {
+            throw new Error(`Cannot verify ownership of shell process group ${pid}`);
+        }
+        return members;
+    }
+    terminate(pid) {
+        const execution = this.#executions.get(pid);
+        if (!execution)
+            return;
+        if (execution.state === "active" && process.platform !== "win32") {
+            // The launching ChildProcess has not delivered its exit event yet.
+            execution.members = readShellProcessGroup(pid);
+        }
+        execution.state = "terminating";
+        if (process.platform === "win32") {
+            killProcessTree(pid);
+        }
+        else if (this.#members(pid, execution).length > 0) {
+            // Never fall back to a recycled leader PID when its group has disappeared.
+            try {
+                process.kill(-pid, "SIGKILL");
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    throw error;
+            }
+        }
     }
     releaseIfExited(pid) {
-        if (!isAlive(pid)) {
-            this.#pids.delete(pid);
+        const execution = this.#executions.get(pid);
+        if (!execution)
+            return;
+        let alive;
+        if (process.platform === "win32") {
+            try {
+                process.kill(pid, 0);
+                alive = true;
+            }
+            catch {
+                alive = false;
+            }
+        }
+        else {
+            alive = this.#members(pid, execution).length > 0;
+        }
+        if (!alive) {
+            this.#publish(pid, execution, "session", "terminated");
+            this.#executions.delete(pid);
             untrackDetachedChildPid(pid);
         }
     }
     get count() {
-        for (const pid of this.#pids)
+        for (const pid of this.#executions.keys())
             this.releaseIfExited(pid);
-        return this.#pids.size;
+        return this.#executions.size;
     }
     async terminateAll() {
-        const pids = [...this.#pids];
+        const pids = [...this.#executions.keys()];
         for (const pid of pids)
-            killProcessTree(pid);
+            this.terminate(pid);
         const deadline = performance.now() + 5_000;
         for (const pid of pids) {
-            while (isAlive(pid)) {
-                // Linux PID 1 may leave orphaned zombies unreaped. Zombies are terminated,
-                // but kill(0) still sees their process group until the parent reaps them.
-                if (process.platform !== "win32") {
-                    const result = spawnSync("ps", ["-eo", "pgid=,stat="], { encoding: "utf8", timeout: 1_000 });
-                    if (result.status === 0 &&
-                        !result.stdout.split("\n").some((line) => {
-                            const [group, state] = line.trim().split(/\s+/);
-                            return Number(group) === pid && state && !state.startsWith("Z");
-                        }))
-                        break;
-                }
+            while (this.#executions.has(pid)) {
+                this.releaseIfExited(pid);
+                if (!this.#executions.has(pid))
+                    break;
                 if (performance.now() >= deadline)
                     throw new Error(`Shell process group ${pid} did not terminate`);
                 await delay(25);
             }
-            this.#pids.delete(pid);
-            untrackDetachedChildPid(pid);
         }
     }
 }

package/dist/utils/shell-process-identity.d.ts

@@ -0,0 +1,11 @@
+export declare const SHELL_EXECUTION_ID_ENV = "DIFFEX_SHELL_EXECUTION_ID";
+export interface ShellProcessIdentity {
+    readonly pid: number;
+    readonly processGroupId: number;
+    /** Linux boot ID and start ticks, or macOS ps lstart in UTC and the C locale. */
+    readonly startTime: string;
+}
+/** Read live group members without treating orphaned zombies as running work. */
+export declare function readShellProcessGroup(processGroupId: number): ShellProcessIdentity[];
+/** The launch token prevents a recycled group ID from authorizing a signal. */
+export declare function hasShellExecutionToken(pid: number, executionId: string): boolean;

package/dist/utils/shell-process-identity.js

@@ -0,0 +1,61 @@
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+export const SHELL_EXECUTION_ID_ENV = "DIFFEX_SHELL_EXECUTION_ID";
+/** Read live group members without treating orphaned zombies as running work. */
+export function readShellProcessGroup(processGroupId) {
+    if (process.platform === "linux") {
+        const bootId = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+        const members = [];
+        for (const name of readdirSync("/proc")) {
+            if (!/^\d+$/.test(name))
+                continue;
+            try {
+                const stat = readFileSync(`/proc/${name}/stat`, "utf8");
+                const fields = stat
+                    .slice(stat.lastIndexOf(")") + 2)
+                    .trim()
+                    .split(/\s+/);
+                if (Number(fields[2]) !== processGroupId || fields[0] === "Z")
+                    continue;
+                members.push({ pid: Number(name), processGroupId, startTime: `${bootId}:${fields[19]}` });
+            }
+            catch (error) {
+                if (["ENOENT", "ESRCH"].includes(error.code ?? ""))
+                    continue;
+                throw error;
+            }
+        }
+        return members;
+    }
+    const result = spawnSync("ps", ["-axo", "pid=,pgid=,stat=,lstart="], {
+        encoding: "utf8",
+        timeout: 1_000,
+        env: { ...process.env, LC_ALL: "C", TZ: "UTC" },
+    });
+    if (result.status !== 0)
+        throw new Error("Cannot inspect shell process groups", { cause: result.error });
+    return result.stdout.split("\n").flatMap((line) => {
+        const [pid, group, state, ...started] = line.trim().split(/\s+/);
+        return Number(group) === processGroupId && state && !state.startsWith("Z")
+            ? [{ pid: Number(pid), processGroupId, startTime: started.join(" ") }]
+            : [];
+    });
+}
+/** The launch token prevents a recycled group ID from authorizing a signal. */
+export function hasShellExecutionToken(pid, executionId) {
+    try {
+        const token = `${SHELL_EXECUTION_ID_ENV}=${executionId}`;
+        if (process.platform === "linux") {
+            return readFileSync(`/proc/${pid}/environ`, "utf8").split("\0").includes(token);
+        }
+        const result = spawnSync("ps", ["-Eww", "-p", String(pid), "-o", "command="], {
+            encoding: "utf8",
+            timeout: 1_000,
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        return result.status === 0 && result.stdout.split(/\s+/).includes(token);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/shell.d.ts

@@ -21,7 +21,7 @@ export declare function getShellEnv(): NodeJS.ProcessEnv;
  * - Characters with undefined code points
  */
 export declare function sanitizeBinaryOutput(str: string): string;
-export declare function trackDetachedChildPid(pid: number): void;
+export declare function trackDetachedChildPid(pid: number, terminate?: () => void): void;
 export declare function untrackDetachedChildPid(pid: number): void;
 export declare function killTrackedDetachedChildren(): void;
 /**

package/dist/utils/shell.js

@@ -153,16 +153,16 @@ export function sanitizeBinaryOutput(str) {
  * Detached child processes must be tracked so they can be killed on parent
  * shutdown signals (SIGHUP/SIGTERM).
  */
-const trackedDetachedChildPids = new Set();
-export function trackDetachedChildPid(pid) {
-    trackedDetachedChildPids.add(pid);
+const trackedDetachedChildPids = new Map();
+export function trackDetachedChildPid(pid, terminate = () => killProcessTree(pid)) {
+    trackedDetachedChildPids.set(pid, terminate);
 }
 export function untrackDetachedChildPid(pid) {
     trackedDetachedChildPids.delete(pid);
 }
 export function killTrackedDetachedChildren() {
-    for (const pid of trackedDetachedChildPids) {
-        killProcessTree(pid);
+    for (const terminate of trackedDetachedChildPids.values()) {
+        terminate();
     }
     trackedDetachedChildPids.clear();
 }

package/distribution-components.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "@diffexai/diffex",
-    "version": "0.3.0",
-    "sourceCommit": "c8cec4d3820393131eaae7b43d56ac5f75d8041a",
+    "version": "0.3.2",
+    "sourceCommit": "57dbba8a810d2e4cc81e48a30a4f5736e0e2d5bf",
     "license": "Apache-2.0",
     "portions": "Diffex contributions; Pi-derived portions retain MIT terms in LICENSE",
     "notice": "LICENSE",
@@ -10,7 +10,7 @@
   },
   {
     "name": "@diffexai/diffex-evolution",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/vendor/evolution: runtime JavaScript and declarations",
     "notice": "LICENSE",
@@ -18,7 +18,7 @@
   },
   {
     "name": "@diffexai/diffex-harness-trace",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/vendor/harness-trace: runtime JavaScript and declarations",
     "notice": "LICENSE",
@@ -134,7 +134,7 @@
   },
   {
     "name": "@diffexai/diffex-agent-core",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/node_modules/@diffexai/diffex-agent-core: bundled runtime, declarations, approved assets and native prebuilds",
     "notice": "dist/node_modules/@diffexai/diffex-agent-core/LICENSE",
@@ -142,7 +142,7 @@
   },
   {
     "name": "@diffexai/diffex-ai",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/node_modules/@diffexai/diffex-ai: bundled runtime, declarations, approved assets and native prebuilds",
     "notice": "dist/node_modules/@diffexai/diffex-ai/LICENSE",
@@ -150,7 +150,7 @@
   },
   {
     "name": "@diffexai/diffex-client",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/node_modules/@diffexai/diffex-client: bundled runtime, declarations, approved assets and native prebuilds",
     "notice": "dist/node_modules/@diffexai/diffex-client/LICENSE",
@@ -158,7 +158,7 @@
   },
   {
     "name": "@diffexai/diffex-harness-state",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/node_modules/@diffexai/diffex-harness-state: bundled runtime, declarations, approved assets and native prebuilds",
     "notice": "dist/node_modules/@diffexai/diffex-harness-state/LICENSE",
@@ -166,7 +166,7 @@
   },
   {
     "name": "@diffexai/diffex-protocol",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/node_modules/@diffexai/diffex-protocol: bundled runtime, declarations, approved assets and native prebuilds",
     "notice": "dist/node_modules/@diffexai/diffex-protocol/LICENSE",
@@ -174,7 +174,7 @@
   },
   {
     "name": "@diffexai/diffex-telemetry",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/node_modules/@diffexai/diffex-telemetry: bundled runtime, declarations, approved assets and native prebuilds",
     "notice": "dist/node_modules/@diffexai/diffex-telemetry/LICENSE",
@@ -182,7 +182,7 @@
   },
   {
     "name": "@diffexai/diffex-tui",
-    "version": "0.3.0",
+    "version": "0.3.2",
     "license": "Apache-2.0",
     "portions": "dist/node_modules/@diffexai/diffex-tui: bundled runtime, declarations, approved assets and native prebuilds",
     "notice": "dist/node_modules/@diffexai/diffex-tui/LICENSE",