@zq-silk/yui 0.5.3 → 0.6.1

package/dist/controller/resourceInventoryLinux.js

@@ -1,24 +1,26 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
-import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { activeLiveRoleAgentSession } from "../executor/agentExecutor.js";
 import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
 import { NodeCommandExecutor } from "../tmux/commandExecutor.js";
 import { TmuxManager, yuiTmuxServerName } from "../tmux/tmuxManager.js";
+import { tmuxSocketDirectory, tmuxSocketEnvironment } from "../tmux/tmuxSocketEndpoint.js";
 import { readControllerDiscovery } from "../core/controllerClient.js";
 import { CONTROLLER_DISCOVERY_PATH } from "../core/protocol.js";
 import { controllerSocketPath } from "../core/controllerEndpoint.js";
 import { buildControllerResourceInventory } from "./resourceInventory.js";
 import { CONTROLLER_DOMAIN_PATH, EPHEMERAL_DOMAIN_GRACE_MS, ephemeralDomainFingerprint, readEphemeralDomainIdentity, readLinuxProcessStartIdentity } from "./domainIdentity.js";
+const LINUX_PROCESS_SCAN_BATCH_SIZE = 64;
+export const INVENTORY_EVENT_LOOP_TURN_BUDGET_MS = 25;
 export async function scanControllerResourceInventory(options) {
     const currentHome = resolve(options.currentHome);
     const environment = options.environment ?? process.env;
     const observedAt = (options.now ?? (() => new Date()))();
     const warnings = [];
     const activeSockets = readActiveUnixSocketPaths(warnings);
-    const processes = listLinuxProcesses(warnings)
+    const processes = (await listLinuxProcesses(warnings))
         .filter(({ pid }) => pid !== process.pid);
     const homes = new Set([currentHome]);
     if (options.scope === "all") {
@@ -27,22 +29,31 @@ export async function scanControllerResourceInventory(options) {
                 homes.add(process.yuiHome);
         }
     }
-    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
-    const rawTmuxArtifacts = listSocketArtifacts(join(tmpdir(), `tmux-${uid}`), /^yui-[a-f0-9]{24}$/u, "tmux-socket", activeSockets);
+    const tmuxDirectory = tmuxSocketDirectory(environment);
+    const listTmuxSocketArtifacts = options.listTmuxSocketArtifacts
+        ?? listSharedTmuxSocketArtifacts;
+    // scope=current owns exactly one YUI_HOME, so only its exact tmux server
+    // socket is observable. Enumerating the whole shared directory (readdir +
+    // lstat per entry) blocked the event loop for seconds under a large
+    // unrelated yui-* population and starved control commands. scope=all keeps
+    // the full cross-domain enumeration for global cleanup reporting.
+    const rawTmuxArtifacts = options.scope === "all"
+        ? listTmuxSocketArtifacts(tmuxDirectory, activeSockets)
+        : inspectExactTmuxSocket(currentHome, tmuxDirectory, activeSockets);
     const homeFacts = [];
     const associatedArtifacts = new Set();
     for (const home of [...homes].sort()) {
         const matchingProcesses = processes.filter(({ yuiHome }) => yuiHome === home);
         const state = loadHomeState(home, warnings, options);
         const domain = inspectRuntimeDomain(home, matchingProcesses, state.roles, state.storageStatus, observedAt);
-        const tmuxSocketPath = join(tmpdir(), `tmux-${uid}`, yuiTmuxServerName(home));
+        const tmuxSocketPath = join(tmuxDirectory, yuiTmuxServerName(home));
         const tmuxArtifact = rawTmuxArtifacts.find(({ path }) => path === tmuxSocketPath);
         if (tmuxArtifact !== undefined)
             associatedArtifacts.add(tmuxArtifact.path);
         const panes = options.panes !== undefined
             ? options.panes
             : tmuxArtifact?.active === true
-                ? inspectHomePanes(home, environment.YUI_TMUX_BIN ?? "tmux", warnings)
+                ? inspectHomePanes(home, environment, warnings)
                 : [];
         const discovery = await inspectDiscovery(home, matchingProcesses, activeSockets);
         if (discovery.status === "valid"
@@ -164,7 +175,7 @@ export function classifyRuntimeProcess(args, command) {
         return "agent";
     return "other";
 }
-function listLinuxProcesses(warnings) {
+async function listLinuxProcesses(warnings) {
     const uid = typeof process.getuid === "function" ? process.getuid() : 0;
     const clockTicks = readClockTicks();
     const uptimeMs = readSystemUptimeMs();
@@ -179,21 +190,21 @@ function listLinuxProcesses(warnings) {
         warnings.push(`Cannot enumerate Linux processes: ${message(error)}`);
         return [];
     }
-    return entries.flatMap((entryName) => {
+    const result = [];
+    await forEachInEventLoopBatches(entries, LINUX_PROCESS_SCAN_BATCH_SIZE, (entryName) => {
+        const pid = linuxProcessEntryPid(entryName);
+        if (pid === undefined)
+            return;
         try {
-            const pid = linuxProcessEntryPid(entryName);
-            if (pid === undefined)
-                return [];
             const status = readFileSync(`/proc/${pid}/status`, "utf8");
             const processUid = parseStatusNumber(status, "Uid");
-            if (processUid !== uid)
-                return [];
-            const parsed = parseLinuxProcessStat(readFileSync(`/proc/${pid}/stat`, "utf8"), clockTicks, uptimeMs);
-            const args = splitNullDelimited(readFileSync(`/proc/${pid}/cmdline`));
-            const command = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
-            const yuiHome = readYuiHome(pid);
-            const io = readProcessIo(pid);
-            return [{
+            if (processUid === uid) {
+                const parsed = parseLinuxProcessStat(readFileSync(`/proc/${pid}/stat`, "utf8"), clockTicks, uptimeMs);
+                const args = splitNullDelimited(readFileSync(`/proc/${pid}/cmdline`));
+                const command = readFileSync(`/proc/${pid}/comm`, "utf8").trim();
+                const yuiHome = readYuiHome(pid);
+                const io = readProcessIo(pid);
+                result.push({
                     pid,
                     ppid: parsed.ppid,
                     uid: processUid,
@@ -206,14 +217,35 @@ function listLinuxProcesses(warnings) {
                     cpuTimeMs: parsed.cpuTimeMs,
                     ...(io === undefined ? {} : io),
                     ageMs: parsed.ageMs
-                }];
+                });
+            }
         }
         catch {
             // Processes commonly exit during a /proc scan. A point-in-time inventory
             // omits those races instead of turning them into persistent warnings.
-            return [];
         }
     });
+    return result;
+}
+/** Cooperatively visits synchronous inventory entries in bounded turns. */
+export async function forEachInEventLoopBatches(entries, batchSize, visit, timing = {}) {
+    if (!Number.isSafeInteger(batchSize) || batchSize < 1) {
+        throw new Error("Event-loop batch size must be a positive integer.");
+    }
+    const now = timing.now ?? (() => performance.now());
+    let turnStartedAt = now();
+    let entriesInTurn = 0;
+    for (let index = 0; index < entries.length; index += 1) {
+        visit(entries[index], index);
+        entriesInTurn += 1;
+        if (index + 1 < entries.length
+            && (entriesInTurn >= batchSize
+                || now() - turnStartedAt >= INVENTORY_EVENT_LOOP_TURN_BUDGET_MS)) {
+            await new Promise((resolve) => setImmediate(resolve));
+            turnStartedAt = now();
+            entriesInTurn = 0;
+        }
+    }
 }
 /**
  * Resolve one numeric /proc entry name without asking the filesystem for
@@ -304,28 +336,36 @@ function listSocketArtifacts(directory, pattern, artifactKind, activeSockets) {
         return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
             if (!pattern.test(entry.name))
                 return [];
-            const path = join(directory, entry.name);
-            let metadata;
-            try {
-                metadata = lstatSync(path);
-            }
-            catch {
-                return [];
-            }
-            if (!metadata.isSocket())
-                return [];
-            return [{
-                    artifactKind,
-                    path,
-                    active: activeSockets.has(path),
-                    fingerprint: statFingerprint(metadata)
-                }];
+            return inspectSocketArtifact(join(directory, entry.name), artifactKind, activeSockets);
         });
     }
     catch {
         return [];
     }
 }
+function listSharedTmuxSocketArtifacts(directory, activeSockets) {
+    return listSocketArtifacts(directory, /^yui-[a-f0-9]{24}$/u, "tmux-socket", activeSockets);
+}
+function inspectExactTmuxSocket(currentHome, tmuxDirectory, activeSockets) {
+    return inspectSocketArtifact(join(tmuxDirectory, yuiTmuxServerName(currentHome)), "tmux-socket", activeSockets);
+}
+function inspectSocketArtifact(path, artifactKind, activeSockets) {
+    let metadata;
+    try {
+        metadata = lstatSync(path);
+    }
+    catch {
+        return [];
+    }
+    if (!metadata.isSocket())
+        return [];
+    return [{
+            artifactKind,
+            path,
+            active: activeSockets.has(path),
+            fingerprint: statFingerprint(metadata)
+        }];
+}
 async function inspectDiscovery(home, processes, activeSockets) {
     const path = join(home, CONTROLLER_DISCOVERY_PATH);
     try {
@@ -576,9 +616,20 @@ function loadHomeState(home, warnings, options) {
         return { storageStatus: "invalid", roles: [] };
     }
 }
-function inspectHomePanes(home, tmuxBin, warnings) {
+function inspectHomePanes(home, environment, warnings) {
     try {
-        return new TmuxManager(tmuxBin, new NodeCommandExecutor(), {
+        const executor = new NodeCommandExecutor();
+        const commandEnvironment = tmuxSocketEnvironment(environment);
+        return new TmuxManager(environment.YUI_TMUX_BIN ?? "tmux", {
+            run: (command, args, options) => executor.run(command, args, {
+                ...options,
+                environment: {
+                    ...commandEnvironment,
+                    ...options?.environment,
+                    TMUX_TMPDIR: commandEnvironment.TMUX_TMPDIR
+                }
+            })
+        }, {
             yuiHome: home
         }).inspectRolePaneInventory();
     }

package/dist/controller/resourceInventoryRpc.js

@@ -0,0 +1,85 @@
+/**
+ * Bounded RPC client for the resource inventory Worker Thread
+ * (task-21, work-item-6).
+ *
+ * The `/proc` scanning in `resourceInventoryLinux` is blocking IO (hundreds of
+ * `readFileSync` calls per pass, `spawnSync`, tmux inspection). When the worker
+ * backend is active (`YUI_STORE_BACKEND=sqlite` + `YUI_STORE_WORKER=1`, the same
+ * flag as the persistence worker, §6), the Controller runtime and the ephemeral
+ * reaper scan through this client instead: the scan runs in the inventory
+ * worker (its own thread), the main event loop stays free, and the result is
+ * posted back at the same cadence (design §3.3).
+ *
+ * The backpressure, cancellation, and fault-boundary machinery is the shared
+ * `core/boundedRpc` client; this module adds the inventory dialect:
+ *
+ *   main -> worker: init | scan | cancel | shutdown
+ *   worker -> main: ready | result | error
+ *
+ * Only structured-cloneable scan options cross the port (the file-backed
+ * `inspectStorage` / `openCompatibleStore` / `now` seams stay on the direct
+ * path, which the file backend still uses). The inventory worker never touches
+ * the persistence worker's database connection (§3.3): it is a separate worker
+ * with a separate concern.
+ */
+import { BoundedRpcClient, deserializeError, nextRequestId } from "../core/boundedRpc.js";
+// -- Protocol adapter ---------------------------------------------------------
+const inventoryProtocol = {
+    initRequest: () => ({ kind: "init" }),
+    cancelRequest: (requestId) => ({ kind: "cancel", requestId }),
+    shutdownRequest: () => ({ kind: "shutdown" }),
+    isReady: (response) => response.kind === "ready",
+    responseRequestId: (response) => {
+        if (response.kind === "ready") {
+            throw new Error("ready response has no requestId.");
+        }
+        return response.requestId;
+    },
+    settle: (response, settlement) => {
+        if (response.kind === "result") {
+            settlement.resolve(response.inventory);
+            return;
+        }
+        if (response.kind === "error") {
+            settlement.reject(deserializeError(response.error));
+        }
+    }
+};
+// -- Client ------------------------------------------------------------------
+/**
+ * The main-thread client for the inventory worker. `scan` runs the full
+ * `scanControllerResourceInventory` in the worker and resolves with the same
+ * inventory shape the direct call returns; the scheduler and the ephemeral
+ * reaper consume it through the same ports as today (§3.3, behavior unchanged).
+ */
+export class ResourceInventoryClient {
+    #rpc;
+    constructor(options = {}) {
+        this.#rpc = new BoundedRpcClient(inventoryProtocol, {
+            maxInFlight: options.maxInFlight ?? 4,
+            maxQueue: options.maxQueue ?? 16,
+            workerScript: options.workerScript ?? new URL("./resourceInventoryWorker.js", import.meta.url)
+        });
+    }
+    /** Run one resource inventory scan in the worker. */
+    scan(options, rpcOptions) {
+        const requestId = nextRequestId();
+        return this.#rpc.send(requestId, { kind: "scan", requestId, options }, rpcOptions);
+    }
+    /** Close the worker. */
+    close() {
+        return this.#rpc.close();
+    }
+    /** Currently in-flight scans (metrics/tests). */
+    get inFlight() {
+        return this.#rpc.inFlight;
+    }
+    /** Currently queued scans waiting for a slot (metrics/tests). */
+    get queueDepth() {
+        return this.#rpc.queueDepth;
+    }
+    /** Test-only fault injection: terminate the worker (the client restarts it). */
+    crashForTest() {
+        return this.#rpc.crashForTest();
+    }
+}

package/dist/controller/resourceInventoryWorker.js

@@ -0,0 +1,50 @@
+/**
+ * Resource inventory Worker Thread (task-21, work-item-6).
+ *
+ * Runs the blocking `/proc` scanning of `resourceInventoryLinux` off the main
+ * thread. The main thread asks for a scan over a `MessageChannel` port; the
+ * worker runs the exact same `scanControllerResourceInventory` the file backend
+ * calls directly and posts the inventory back. Because worker threads share the
+ * process, the scanner's self-exclusion (`process.pid`, its start identity)
+ * keeps excluding the Controller process exactly as on the main thread.
+ *
+ * The port handshake, dispatch, cancellation observation, and error
+ * serialization are the shared `core/boundedRpc` worker host; this module only
+ * supplies the inventory dialect. The worker is read-only: it never touches the
+ * persistence worker's database connection (§3.3) — it opens the same file
+ * store reads the direct scan uses, in its own thread.
+ *
+ * Protocol (see resourceInventoryRpc.ts):
+ *   main -> worker: init | scan | cancel | shutdown
+ *   worker -> main: ready | result | error
+ */
+import { runRpcWorker } from "../core/boundedRpc.js";
+import { scanControllerResourceInventory } from "./resourceInventoryLinux.js";
+runRpcWorker({
+    kindOf: (request) => (request.kind === "scan" ? "request" : request.kind),
+    requestIdOf: (request) => (request.kind === "scan" || request.kind === "cancel" ? request.requestId : undefined),
+    init: async () => {
+        // No resources to initialize: each scan opens what it needs and closes it.
+    },
+    handle: async (request) => {
+        if (request.kind !== "scan") {
+            throw new Error(`Unexpected inventory request: ${request.kind}`);
+        }
+        return scanControllerResourceInventory(request.options);
+    },
+    cancel: () => {
+        // The /proc scan has no cancellation points. The main thread rejects the
+        // aborted call immediately and suppresses the late result; the worker
+        // thread finishes the scan on its own time without blocking the main loop.
+    },
+    shutdown: async () => {
+        // Nothing to close: scans own no long-lived resources.
+    },
+    ready: () => ({ kind: "ready" }),
+    result: (requestId, value) => ({
+        kind: "result",
+        requestId,
+        inventory: value
+    }),
+    error: (requestId, error) => ({ kind: "error", requestId, error })
+});