@diffexai/diffex 0.2.7 → 0.3.1

package/dist/node_modules/@diffexai/diffex-ai/distribution-components.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "@diffexai/diffex-ai",
-    "version": "0.2.7",
-    "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+    "version": "0.3.1",
+    "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
     "license": "Apache-2.0",
     "portions": "Diffex contributions; Pi-derived portions retain MIT terms in LICENSE",
     "notice": "LICENSE",
@@ -20,7 +20,7 @@
   },
   {
     "name": "@diffexai/diffex-telemetry",
-    "version": "^0.2.7",
+    "version": "^0.3.1",
     "distribution": "resolved separately by package manager; not bundled in this npm tarball"
   },
   {

package/dist/node_modules/@diffexai/diffex-ai/distribution-files.json

@@ -1,5 +1,5 @@
 {
-  "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+  "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
   "algorithm": "sha256",
   "files": [
     {
@@ -676,7 +676,7 @@
     },
     {
       "path": "dist/providers/data/.manifest.json",
-      "sha256": "2cf674e48ce768bfc3ac3b97b175a9d6a53acf00452ee7d1b9c3ead6c6daee7e"
+      "sha256": "e7349cfa428948144bd94d1d6327eb45db4c3d8b50e22d2f10d030d7fb62ad8d"
     },
     {
       "path": "dist/providers/data/amazon-bedrock.json",
@@ -776,15 +776,15 @@
     },
     {
       "path": "dist/providers/data/opencode-go.json",
-      "sha256": "31c4434316c8a1b7fcc637b25f1147dd44da946a0b932ca10fb5ac594261dad7"
+      "sha256": "fa6d6737da943fbb9c36487cb4cd5bc152d1f2fd548280bbe9d35d0304e79f11"
     },
     {
       "path": "dist/providers/data/opencode.json",
-      "sha256": "ce7fcaa9e6da77b00d875b42db03d39332c259338e8e1632e74126d663c8405b"
+      "sha256": "43c5d9cc6fab109411e6ac8eebac4b9fb0b00cff844cf0eb6c1559a08586525f"
     },
     {
       "path": "dist/providers/data/openrouter.json",
-      "sha256": "828095707e092be2e68b8c6a052588188ef651f68d4097d3d72ab183fb5c7b81"
+      "sha256": "a3375b66ad7b4bb61f22d867e132c991d3b9851436c529838c109b9794d59b93"
     },
     {
       "path": "dist/providers/data/qwen-token-plan-cn.json",
@@ -804,7 +804,7 @@
     },
     {
       "path": "dist/providers/data/vercel-ai-gateway.json",
-      "sha256": "e61d139444d16c7900a141d0bc9af874761794e80fb7d3ff4a08a21c3e93231f"
+      "sha256": "03b0830a794af1bc921fb504565534bedec660fcc9482adcf56ec5fb27703e60"
     },
     {
       "path": "dist/providers/data/xai.json",

package/dist/node_modules/@diffexai/diffex-ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffexai/diffex-ai",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Unified LLM API with automatic model discovery and provider configuration",
   "type": "module",
   "main": "./dist/index.js",

package/dist/node_modules/@diffexai/diffex-client/distribution-components.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "@diffexai/diffex-client",
-    "version": "0.2.7",
-    "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+    "version": "0.3.1",
+    "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
     "license": "Apache-2.0",
     "portions": "Diffex contributions; Pi-derived portions retain MIT terms in LICENSE",
     "notice": "LICENSE",
@@ -10,7 +10,7 @@
   },
   {
     "name": "@diffexai/diffex-protocol",
-    "version": "^0.2.7",
+    "version": "^0.3.1",
     "distribution": "resolved separately by package manager; not bundled in this npm tarball"
   }
 ]

package/dist/node_modules/@diffexai/diffex-client/distribution-files.json

@@ -1,5 +1,5 @@
 {
-  "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+  "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
   "algorithm": "sha256",
   "files": [
     {

package/dist/node_modules/@diffexai/diffex-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffexai/diffex-client",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Transport-neutral client for remote Diffex sessions over framed CBOR bytes",
   "type": "module",
   "main": "./dist/index.js",

package/dist/node_modules/@diffexai/diffex-harness-state/distribution-components.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "@diffexai/diffex-harness-state",
-    "version": "0.2.7",
-    "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+    "version": "0.3.1",
+    "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
     "license": "Apache-2.0",
     "portions": "Diffex contributions; Pi-derived portions retain MIT terms in LICENSE",
     "notice": "LICENSE",

package/dist/node_modules/@diffexai/diffex-harness-state/distribution-files.json

@@ -1,5 +1,5 @@
 {
-  "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+  "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
   "algorithm": "sha256",
   "files": [
     {

package/dist/node_modules/@diffexai/diffex-harness-state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffexai/diffex-harness-state",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Persistent harness state schema and bundle storage for Diffex",
   "type": "module",
   "main": "./dist/index.js",

package/dist/node_modules/@diffexai/diffex-protocol/distribution-components.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "@diffexai/diffex-protocol",
-    "version": "0.2.7",
-    "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+    "version": "0.3.1",
+    "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
     "license": "Apache-2.0",
     "portions": "Diffex contributions; Pi-derived portions retain MIT terms in LICENSE",
     "notice": "LICENSE",

package/dist/node_modules/@diffexai/diffex-protocol/distribution-files.json

@@ -1,5 +1,5 @@
 {
-  "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+  "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
   "algorithm": "sha256",
   "files": [
     {

package/dist/node_modules/@diffexai/diffex-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffexai/diffex-protocol",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Transport-neutral CBOR protocol for remote Diffex sessions",
   "type": "module",
   "main": "./dist/index.js",

package/dist/node_modules/@diffexai/diffex-telemetry/distribution-components.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "@diffexai/diffex-telemetry",
-    "version": "0.2.7",
-    "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+    "version": "0.3.1",
+    "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
     "license": "Apache-2.0",
     "portions": "Diffex contributions; Pi-derived portions retain MIT terms in LICENSE",
     "notice": "LICENSE",

package/dist/node_modules/@diffexai/diffex-telemetry/distribution-files.json

@@ -1,5 +1,5 @@
 {
-  "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+  "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
   "algorithm": "sha256",
   "files": [
     {

package/dist/node_modules/@diffexai/diffex-telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffexai/diffex-telemetry",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Vendor-neutral telemetry contracts and typed schema utilities for Diffex",
   "type": "module",
   "main": "./dist/index.js",

package/dist/node_modules/@diffexai/diffex-tui/distribution-components.json

@@ -1,8 +1,8 @@
 [
   {
     "name": "@diffexai/diffex-tui",
-    "version": "0.2.7",
-    "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+    "version": "0.3.1",
+    "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
     "license": "Apache-2.0",
     "portions": "Diffex contributions; Pi-derived portions retain MIT terms in LICENSE",
     "notice": "LICENSE",

package/dist/node_modules/@diffexai/diffex-tui/distribution-files.json

@@ -1,5 +1,5 @@
 {
-  "sourceCommit": "598159fca2acfacdf5374205b5a5e46afe0af58a",
+  "sourceCommit": "9d59a28db4888b6824740505f0a16146667f036b",
   "algorithm": "sha256",
   "files": [
     {

package/dist/node_modules/@diffexai/diffex-tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diffexai/diffex-tui",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "Terminal User Interface library with differential rendering for efficient text-based applications",
   "type": "module",
   "main": "dist/index.js",

package/dist/utils/child-process.d.ts

@@ -13,5 +13,9 @@ export declare function spawnProcessSync(command: string, args: string[], option
  * the grace timer is re-armed on every chunk, so an actively writing descendant keeps
  * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant
  * that never lets `close` fire) still releases us after the grace elapses.
+ * Callers handing background jobs to an environment can explicitly bound draining
+ * with maxPostExitMs so ongoing service output cannot block session disposal.
  */
-export declare function waitForChildProcess(child: ChildProcess): Promise<number | null>;
+export declare function waitForChildProcess(child: ChildProcess, options?: {
+    maxPostExitMs?: number;
+}): Promise<number | null>;

package/dist/utils/child-process.js

@@ -19,16 +19,21 @@ export function spawnProcessSync(command, args, options) {
  * the grace timer is re-armed on every chunk, so an actively writing descendant keeps
  * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant
  * that never lets `close` fire) still releases us after the grace elapses.
+ * Callers handing background jobs to an environment can explicitly bound draining
+ * with maxPostExitMs so ongoing service output cannot block session disposal.
  */
-export function waitForChildProcess(child) {
+export function waitForChildProcess(child, options) {
     return new Promise((resolve, reject) => {
         let settled = false;
         let exited = false;
         let exitCode = null;
         let postExitTimer;
+        let postExitDeadline;
         let stdoutEnded = child.stdout === null;
         let stderrEnded = child.stderr === null;
         const cleanup = () => {
+            if (postExitDeadline)
+                clearTimeout(postExitDeadline);
             if (postExitTimer) {
                 clearTimeout(postExitTimer);
                 postExitTimer = undefined;
@@ -88,6 +93,9 @@ export function waitForChildProcess(child) {
             exitCode = code;
             maybeFinalizeAfterExit();
             if (!settled) {
+                if (options?.maxPostExitMs !== undefined) {
+                    postExitDeadline = setTimeout(() => finalize(exitCode), options.maxPostExitMs);
+                }
                 armIdleTimer();
             }
         };

package/dist/utils/owned-shell-processes.d.ts

@@ -0,0 +1,29 @@
+import { type ShellProcessIdentity } from "./shell-process-identity.ts";
+export type BackgroundProcessPolicy = {
+    readonly lifetime: "session";
+} | {
+    readonly lifetime: "environment";
+    readonly ownershipDirectory: string;
+};
+export interface ShellOwnershipRecord {
+    readonly version: 1;
+    readonly executionId: string;
+    readonly owner: "session" | "environment";
+    readonly state: "active" | "background" | "terminated";
+    readonly processGroupId: number;
+    readonly supervisorPid: number;
+    readonly members: readonly ShellProcessIdentity[];
+}
+/** Session ownership ends only after a successful, durably published handoff. */
+export declare class OwnedShellProcesses {
+    #private;
+    readonly policy: BackgroundProcessPolicy;
+    constructor(policy?: BackgroundProcessPolicy);
+    track(pid: number, executionId: string): void;
+    /** Called synchronously on shell exit, before output draining or another event can cancel it. */
+    complete(pid: number, successful: boolean): void;
+    terminate(pid: number): void;
+    releaseIfExited(pid: number): void;
+    get count(): number;
+    terminateAll(): Promise<void>;
+}

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

@@ -0,0 +1,171 @@
+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";
+import { hasShellExecutionToken, readShellProcessGroup } from "./shell-process-identity.js";
+/** Session ownership ends only after a successful, durably published handoff. */
+export class OwnedShellProcesses {
+    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) {
+        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.#executions.keys())
+            this.releaseIfExited(pid);
+        return this.#executions.size;
+    }
+    async terminateAll() {
+        const pids = [...this.#executions.keys()];
+        for (const pid of pids)
+            this.terminate(pid);
+        const deadline = performance.now() + 5_000;
+        for (const pid of pids) {
+            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);
+            }
+        }
+    }
+}

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();
 }