@zq-silk/yui 0.6.0 → 0.6.2

package/dist/runtime/sessionOwnerIdentity.js

@@ -0,0 +1,269 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { requireSafeIdentity, requireText, requireTimestamp } from "./validation.js";
+/** Validates and freezes one physical owner record; fails closed on malformed input. */
+export function createSessionOwnerIdentity(input) {
+    const owner = input.owner;
+    if (owner.scope !== "task" && owner.scope !== "global") {
+        throw new TypeError("Session owner scope is invalid.");
+    }
+    if (owner.scope === "task" && owner.taskId === undefined) {
+        throw new TypeError("Task session owner requires a task id.");
+    }
+    if (owner.scope === "global" && owner.taskId !== undefined) {
+        throw new TypeError("Global session owner must not carry a task id.");
+    }
+    const providerRoot = input.providerRoot;
+    if (!Number.isSafeInteger(providerRoot.pid) || providerRoot.pid <= 0) {
+        throw new TypeError("Session owner provider root pid is invalid.");
+    }
+    if (!/^[0-9]{1,32}$/u.test(providerRoot.startIdentity)) {
+        throw new TypeError("Session owner provider start identity is invalid.");
+    }
+    if (providerRoot.processGroupId !== undefined
+        && (!Number.isSafeInteger(providerRoot.processGroupId) || providerRoot.processGroupId <= 0)) {
+        throw new TypeError("Session owner process group id is invalid.");
+    }
+    if (providerRoot.processSessionId !== undefined
+        && (!Number.isSafeInteger(providerRoot.processSessionId) || providerRoot.processSessionId <= 0)) {
+        throw new TypeError("Session owner process session id is invalid.");
+    }
+    const tmux = input.tmux;
+    return Object.freeze({
+        schemaVersion: 1,
+        kind: "yui-session-owner",
+        owner: Object.freeze({
+            scope: owner.scope,
+            ...(owner.taskId === undefined ? {} : { taskId: requireSafeIdentity(owner.taskId, "Task id") }),
+            roleName: requireSafeIdentity(owner.roleName, "Role name")
+        }),
+        agentId: requireSafeIdentity(input.agentId, "Agent id"),
+        adapterId: requireText(input.adapterId, "Adapter id"),
+        launchId: requireSafeIdentity(input.launchId, "Launch id"),
+        ...(input.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: requireText(input.nativeSessionId, "Native session id") }),
+        tmux: Object.freeze({
+            serverName: requireText(tmux.serverName, "tmux server name"),
+            socketPath: requireText(tmux.socketPath, "tmux socket path"),
+            sessionName: requireText(tmux.sessionName, "tmux session name"),
+            windowName: requireText(tmux.windowName, "tmux window name"),
+            ...(tmux.panePid === undefined ? {} : { panePid: tmux.panePid })
+        }),
+        providerRoot: Object.freeze({
+            pid: providerRoot.pid,
+            startIdentity: providerRoot.startIdentity,
+            ...(providerRoot.processGroupId === undefined
+                ? {}
+                : { processGroupId: providerRoot.processGroupId }),
+            ...(providerRoot.processSessionId === undefined
+                ? {}
+                : { processSessionId: providerRoot.processSessionId }),
+            attribution: providerRoot.attribution
+        }),
+        ...(input.runtimeRoot === undefined ? {} : { runtimeRoot: input.runtimeRoot }),
+        recordedAt: requireTimestamp(input.recordedAt, "Recorded at")
+    });
+}
+/**
+ * Reads one Linux process identity from /proc. Returns undefined when /proc is
+ * unavailable, unreadable, or the platform does not expose it — the caller
+ * must treat that as a verification gap, never as proof of absence.
+ */
+export function readLinuxProcessIdentity(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return undefined;
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const closing = stat.lastIndexOf(")");
+        if (closing < 0)
+            return undefined;
+        const fields = stat.slice(closing + 1).trim().split(/\s+/u);
+        const state = fields[0];
+        const processGroupId = Number(fields[2]);
+        const processSessionId = Number(fields[3]);
+        const startIdentity = fields[19];
+        if (startIdentity === undefined || !/^[0-9]{1,32}$/u.test(startIdentity)) {
+            return undefined;
+        }
+        const rssBytes = readLinuxProcessRssBytes(pid) ?? 0;
+        return {
+            pid,
+            startIdentity,
+            ...(typeof state === "string" && state.length > 0 ? { state } : {}),
+            ...(Number.isSafeInteger(processGroupId) && processGroupId > 0
+                ? { processGroupId }
+                : {}),
+            ...(Number.isSafeInteger(processSessionId) && processSessionId > 0
+                ? { processSessionId }
+                : {}),
+            rssBytes
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function readLinuxProcessRssBytes(pid) {
+    try {
+        const status = readFileSync(`/proc/${pid}/status`, "utf8");
+        for (const line of status.split("\n")) {
+            if (line.startsWith("VmRSS:")) {
+                const value = Number(line.slice("VmRSS:".length).trim().split(/\s+/u)[0]);
+                if (Number.isFinite(value) && value >= 0)
+                    return Math.round(value) * 1024;
+            }
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * True only when /proc still holds the exact process identity. A reused PID
+ * with a different start identity is absent, not live.
+ */
+export function isLinuxProcessLive(pid, startIdentity) {
+    const current = readLinuxProcessIdentity(pid);
+    if (current === undefined)
+        return false;
+    // A zombie has already exited; only the task struct remains for the parent
+    // to reap. It cannot execute or hold resources, so it is not live.
+    if (current.state === "Z")
+        return false;
+    return current.startIdentity === startIdentity;
+}
+/**
+ * Discovers the Provider root for one launch by the exact YUI_LAUNCH_ID
+ * environment fence. Returns undefined when no same-user process carries the
+ * fence — the caller must not guess from a process name or cwd.
+ */
+export function discoverProviderRootByLaunchEnv(launchId) {
+    const matches = listLaunchFencedProcesses(launchId);
+    for (const pid of matches) {
+        const identity = readLinuxProcessIdentity(pid);
+        if (identity !== undefined)
+            return { pid, identity };
+    }
+    return undefined;
+}
+/**
+ * Lists every live process whose initial environment carries the exact
+ * `YUI_LAUNCH_ID=<launchId>` fence. The fence is inherited by Provider
+ * children, so this is the exact, PID-reuse-safe attribution for a surviving
+ * child after its root has exited: a recycled PID never carries the fence.
+ * Processes without the fence are unattributed and must never be signaled.
+ */
+export function listLaunchFencedProcesses(launchId) {
+    if (!Number.isSafeInteger(launchId) && !/^[A-Za-z0-9_.:-]+$/u.test(launchId)) {
+        return [];
+    }
+    let entries;
+    try {
+        entries = readdirSync("/proc", { encoding: "utf8" });
+    }
+    catch {
+        return [];
+    }
+    const needle = `YUI_LAUNCH_ID=${launchId}`;
+    const matches = [];
+    for (const entry of entries) {
+        if (!/^[0-9]+$/u.test(entry))
+            continue;
+        const pid = Number(entry);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            continue;
+        let environment;
+        try {
+            environment = readFileSync(`/proc/${pid}/environ`, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!environment.includes(needle))
+            continue;
+        matches.push(pid);
+    }
+    return matches;
+}
+/**
+ * Lists the process tree owned by one Provider root: the root itself plus
+ * descendants proven by process-group membership or an ancestor chain. A
+ * process that merely shares a name or cwd is never included.
+ */
+export function listOwnedProcessTree(rootPid, rootProcessGroupId) {
+    let entries;
+    try {
+        entries = readdirSync("/proc", { encoding: "utf8" });
+    }
+    catch {
+        return [];
+    }
+    const processes = new Map();
+    for (const entry of entries) {
+        if (!/^[0-9]+$/u.test(entry))
+            continue;
+        const pid = Number(entry);
+        if (!Number.isSafeInteger(pid) || pid <= 0)
+            continue;
+        try {
+            const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+            const closing = stat.lastIndexOf(")");
+            if (closing < 0)
+                continue;
+            const fields = stat.slice(closing + 1).trim().split(/\s+/u);
+            const ppid = Number(fields[1]);
+            const processGroupId = Number(fields[2]);
+            const startIdentity = fields[19];
+            if (!Number.isSafeInteger(ppid)
+                || ppid < 0
+                || startIdentity === undefined
+                || !/^[0-9]{1,32}$/u.test(startIdentity)) {
+                continue;
+            }
+            if (rootProcessGroupId !== undefined
+                && Number.isSafeInteger(processGroupId)
+                && processGroupId === rootProcessGroupId) {
+                const identity = readLinuxProcessIdentity(pid);
+                if (identity !== undefined) {
+                    processes.set(pid, { ppid, identity });
+                }
+                continue;
+            }
+            processes.set(pid, {
+                ppid,
+                identity: {
+                    pid,
+                    startIdentity,
+                    ...(Number.isSafeInteger(processGroupId) && processGroupId > 0
+                        ? { processGroupId }
+                        : {}),
+                    rssBytes: readLinuxProcessRssBytes(pid) ?? 0
+                }
+            });
+        }
+        catch {
+            // A process exiting mid-scan is simply omitted from this point-in-time
+            // tree; the termination guard re-verifies the root identity afterwards.
+        }
+    }
+    const owned = new Map();
+    const root = processes.get(rootPid);
+    if (root === undefined)
+        return [];
+    owned.set(rootPid, root.identity);
+    // Ancestry walk: any process whose parent chain reaches the root is owned.
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [pid, process] of processes) {
+            if (owned.has(pid))
+                continue;
+            if (owned.has(process.ppid)) {
+                owned.set(pid, process.identity);
+                grew = true;
+            }
+        }
+    }
+    return [...owned.values()];
+}

package/dist/runtime/sessionOwnerRegistry.js

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createSessionOwnerIdentity } from "./sessionOwnerIdentity.js";
+/**
+ * Durable, enumerable physical owner records for runtime generations.
+ *
+ * One JSON file per launch id under `<home>/runtime/session-owners/`. The
+ * directory is runtime state (like the tmux socket), not aggregate domain
+ * state, so it needs no schema migration; it survives a Controller restart and
+ * stays enumerable after the durable Session map or history is cleared, which
+ * is exactly the gap the audit proved (durable pointers empty, physical
+ * processes still live).
+ */
+export class FileSessionOwnerRegistry {
+    #directory;
+    constructor(home) {
+        this.#directory = join(resolve(home), "runtime", "session-owners");
+    }
+    get directory() {
+        return this.#directory;
+    }
+    /** Atomically records (or replaces) one generation's owner identity. */
+    record(identity) {
+        mkdirSync(this.#directory, { recursive: true, mode: 0o700 });
+        const target = this.#path(identity.launchId);
+        const temporary = `${target}.tmp-${process.pid}`;
+        writeFileSync(temporary, JSON.stringify(identity, null, 2) + "\n", { mode: 0o600 });
+        renameSync(temporary, target);
+    }
+    get(launchId) {
+        if (!isSafeLaunchId(launchId))
+            return null;
+        try {
+            return parseOwnerRecord(readFileSync(this.#path(launchId), "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    list() {
+        let entries;
+        try {
+            entries = readdirSync(this.#directory, { encoding: "utf8" });
+        }
+        catch {
+            return [];
+        }
+        const records = [];
+        for (const entry of entries) {
+            if (!entry.endsWith(".json"))
+                continue;
+            try {
+                records.push(parseOwnerRecord(readFileSync(join(this.#directory, entry), "utf8")));
+            }
+            catch {
+                // A malformed record must not hide the exact candidates beside it.
+            }
+        }
+        records.sort((left, right) => left.recordedAt.localeCompare(right.recordedAt));
+        return records;
+    }
+    listForOwner(owner) {
+        return this.list().filter((record) => (record.owner.scope === owner.scope
+            && (owner.scope === "global"
+                || record.owner.taskId === owner.taskId)
+            && record.owner.roleName === owner.roleName));
+    }
+    /** Removes a record whose physical resources were proven absent. */
+    remove(launchId) {
+        if (!isSafeLaunchId(launchId))
+            return;
+        try {
+            rmSync(this.#path(launchId), { force: true });
+        }
+        catch {
+            // A stale record is harmless: reconciliation re-verifies physical
+            // identity before acting on it.
+        }
+    }
+    exists() {
+        return existsSync(this.#directory);
+    }
+    #path(launchId) {
+        return join(this.#directory, `${launchId}.json`);
+    }
+}
+function isSafeLaunchId(launchId) {
+    return /^[A-Za-z0-9_.:-]+$/u.test(launchId);
+}
+function parseOwnerRecord(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new Error("Session owner record is invalid.");
+    }
+    const record = parsed;
+    const owner = record.owner;
+    const tmux = record.tmux;
+    const providerRoot = record.providerRoot;
+    return createSessionOwnerIdentity({
+        owner: {
+            scope: owner.scope === "global" ? "global" : "task",
+            ...(owner.taskId === undefined ? {} : { taskId: String(owner.taskId) }),
+            roleName: String(owner.roleName)
+        },
+        agentId: String(record.agentId),
+        adapterId: String(record.adapterId),
+        launchId: String(record.launchId),
+        ...(record.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: String(record.nativeSessionId) }),
+        tmux: {
+            serverName: String(tmux.serverName),
+            socketPath: String(tmux.socketPath),
+            sessionName: String(tmux.sessionName),
+            windowName: String(tmux.windowName),
+            ...(tmux.panePid === undefined ? {} : { panePid: Number(tmux.panePid) })
+        },
+        providerRoot: {
+            pid: Number(providerRoot.pid),
+            startIdentity: String(providerRoot.startIdentity),
+            ...(providerRoot.processGroupId === undefined
+                ? {}
+                : { processGroupId: Number(providerRoot.processGroupId) }),
+            ...(providerRoot.processSessionId === undefined
+                ? {}
+                : { processSessionId: Number(providerRoot.processSessionId) }),
+            attribution: providerRoot.attribution === "pane-pid" ? "pane-pid" : "launch-env"
+        },
+        ...(record.runtimeRoot === undefined ? {} : { runtimeRoot: String(record.runtimeRoot) }),
+        recordedAt: new Date(String(record.recordedAt))
+    });
+}

package/dist/runtime/sessionReconciliation.js

@@ -0,0 +1,93 @@
+/**
+ * Bidirectional durable <-> physical reconciliation for Session generations.
+ *
+ * Durable -> physical: every owner record's Provider root must be absent once
+ * its durable Session is terminal; a live root with a terminal durable state
+ * is the exact leak the audit found. Physical -> durable: the owner registry
+ * stays enumerable after the durable Session map or history is cleared, so a
+ * live generation can always be re-attributed and reported.
+ *
+ * Pure: all I/O is injected. Unknown owners are reported, never cleaned.
+ * An entry is archive-blocking when its durable state is terminal but the
+ * physical Provider root is still live, and the Task is terminal/archived.
+ */
+export function reconcileSessionOwners(input) {
+    const entries = input.records.map((record) => reconcileOne(record, input));
+    const summary = {
+        owners: entries.length,
+        livePhysicalRoots: entries.filter((entry) => entry.physical?.alive === true).length,
+        archiveBlockers: entries.filter((entry) => entry.archiveBlocked).length,
+        verificationGaps: entries.filter((entry) => entry.verificationGap !== undefined).length
+    };
+    return {
+        schemaVersion: 1,
+        observedAt: input.now.toISOString(),
+        entries,
+        summary
+    };
+}
+function reconcileOne(record, input) {
+    const durable = matchDurable(record, input.durable);
+    const physical = input.observe(record);
+    const owner = record.owner;
+    const taskStatus = owner.scope === "task" && owner.taskId !== undefined
+        ? input.taskStatus(owner.taskId)
+        : undefined;
+    const tmuxPane = input.inspectPane(owner.taskId, owner.roleName);
+    const lastStopOutcome = input.lastStopOutcome(owner.taskId, owner.roleName, record.launchId);
+    let mismatch;
+    let verificationGap;
+    if (physical?.identityConflict === true) {
+        mismatch = "identity-conflict";
+    }
+    else if (physical?.alive === true) {
+        if (durable === undefined || durable.status === "stopped" || durable.status === "broken") {
+            mismatch = "durable-terminal-physical-live";
+        }
+    }
+    else if (physical === undefined) {
+        verificationGap = "/proc identity unavailable";
+    }
+    else if (durable !== undefined && durable.status === "running") {
+        mismatch = "durable-live-physical-absent";
+    }
+    const terminalTask = taskStatus === "completed"
+        || taskStatus === "retired"
+        || taskStatus === "archived";
+    const archiveBlocked = mismatch === "durable-terminal-physical-live"
+        && terminalTask;
+    return {
+        owner: {
+            scope: owner.scope,
+            ...(owner.taskId === undefined ? {} : { taskId: owner.taskId }),
+            roleName: owner.roleName
+        },
+        agentId: record.agentId,
+        adapterId: record.adapterId,
+        launchId: record.launchId,
+        ...(record.nativeSessionId === undefined
+            ? {}
+            : { nativeSessionId: record.nativeSessionId }),
+        ...(taskStatus === undefined ? {} : { taskStatus }),
+        durableStatus: durable?.status ?? "absent",
+        ...(tmuxPane === undefined ? {} : { tmuxPane }),
+        ...(physical === undefined ? {} : { physical }),
+        ...(lastStopOutcome === undefined ? {} : { lastStopOutcome }),
+        ...(mismatch === undefined ? {} : { mismatch }),
+        archiveBlocked,
+        ...(verificationGap === undefined ? {} : { verificationGap })
+    };
+}
+function matchDurable(record, durable) {
+    const candidates = durable.filter((fact) => (fact.scope === record.owner.scope
+        && fact.roleName === record.owner.roleName
+        && (record.owner.scope === "global" || fact.taskId === record.owner.taskId)
+        && fact.agentId === record.agentId));
+    const byLaunch = candidates.find((fact) => fact.launchId !== undefined && fact.launchId === record.launchId);
+    if (byLaunch !== undefined)
+        return byLaunch;
+    const byNative = candidates.find((fact) => fact.nativeSessionId !== undefined
+        && record.nativeSessionId !== undefined
+        && fact.nativeSessionId === record.nativeSessionId);
+    return byNative;
+}