@zq-silk/yui 0.6.0 → 0.6.2

package/dist/controller/sessionOwnerReconciliation.js

@@ -0,0 +1,321 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { createSessionOwnerIdentity, discoverProviderRootByLaunchEnv, isLinuxProcessLive, listLaunchFencedProcesses, listOwnedProcessTree, readLinuxProcessIdentity, reconcileSessionOwners, terminateSessionOwners } from "../runtime/index.js";
+import { tmuxSocketDirectory } from "../tmux/tmuxSocketEndpoint.js";
+import { yuiTmuxServerName, yuiTmuxSessionName, yuiTmuxTarget } from "../tmux/tmuxManager.js";
+/**
+ * Production I/O adapters for Issue 03 Session owner reconciliation. The pure
+ * logic lives in src/runtime; this module only binds it to the durable store,
+ * /proc, and the exact tmux namespace of one Home.
+ */
+export class SessionOwnerReconciliation {
+    #home;
+    #store;
+    #environment;
+    #tmux;
+    #onWarning;
+    constructor(deps) {
+        this.#home = deps.home;
+        this.#store = deps.store;
+        this.#environment = deps.environment ?? process.env;
+        this.#tmux = deps.tmux;
+        this.#onWarning = deps.onWarning ?? (() => undefined);
+    }
+    /**
+     * Persists the exact physical owner identity after a host created a new
+     * Provider process. The Provider root is attributed by the exact
+     * YUI_LAUNCH_ID environment fence; the tmux pane PID is only a weaker
+     * fallback when the fence cannot be read.
+     */
+    recordHostOwner(input) {
+        const discovered = discoverProviderRootByLaunchEnv(input.launchId);
+        const fallback = discovered === undefined && input.panePid !== undefined
+            ? readLinuxProcessIdentity(input.panePid)
+            : undefined;
+        const root = discovered ?? (fallback === undefined
+            ? undefined
+            : { pid: fallback.pid, identity: fallback });
+        if (root === undefined) {
+            this.#onWarning(`Session owner identity could not attribute a Provider root for launch ${input.launchId}; `
+                + "no owner record was written.");
+            return;
+        }
+        const owner = input.owner;
+        const taskId = owner.scope === "task" ? owner.taskId : undefined;
+        this.#store.saveSessionOwner(createSessionOwnerIdentity({
+            owner: {
+                scope: owner.scope,
+                ...(taskId === undefined ? {} : { taskId }),
+                roleName: owner.roleName
+            },
+            agentId: input.agentId,
+            adapterId: input.adapterId,
+            launchId: input.launchId,
+            ...(input.nativeSessionId === undefined
+                ? {}
+                : { nativeSessionId: input.nativeSessionId }),
+            tmux: {
+                serverName: yuiTmuxServerName(this.#home),
+                socketPath: join(tmuxSocketDirectory(this.#environment), yuiTmuxServerName(this.#home)),
+                sessionName: owner.scope === "task"
+                    ? yuiTmuxSessionName(this.#home, owner.taskId)
+                    : yuiTmuxSessionName(this.#home, "operator"),
+                windowName: owner.roleName,
+                ...(input.panePid === undefined ? {} : { panePid: input.panePid })
+            },
+            providerRoot: {
+                pid: root.pid,
+                startIdentity: root.identity.startIdentity,
+                ...(root.identity.processGroupId === undefined
+                    ? {}
+                    : { processGroupId: root.identity.processGroupId }),
+                ...(root.identity.processSessionId === undefined
+                    ? {}
+                    : { processSessionId: root.identity.processSessionId }),
+                attribution: discovered === undefined ? "pane-pid" : "launch-env"
+            },
+            ...(input.runtimeRoot === undefined ? {} : { runtimeRoot: input.runtimeRoot }),
+            recordedAt: new Date()
+        }));
+    }
+    /** Read-only bidirectional reconciliation; never mutates physical state. */
+    report() {
+        return reconcileSessionOwners({
+            records: this.#store.listSessionOwners(),
+            durable: durableSessionFacts(this.#store),
+            taskStatus: (taskId) => this.#store.getTask(taskId)?.status,
+            observe: (record) => observeSessionOwnerPhysical(record),
+            inspectPane: (taskId, roleName) => {
+                if (this.#tmux === undefined || taskId === undefined)
+                    return undefined;
+                try {
+                    const pane = this.#tmux.inspectPane(taskId, roleName);
+                    return { target: pane.target, dead: pane.dead };
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            lastStopOutcome: (taskId, roleName, launchId) => (lastSessionTerminationOutcome(this.#store, taskId, roleName, launchId)),
+            now: new Date()
+        });
+    }
+    /**
+     * Stops one owner with physical exit proof. Removes the owner records only
+     * after every root is proven absent; a blocked result preserves them.
+     */
+    async terminateOwner(owner, options = {}) {
+        const records = this.#store.listSessionOwnersForOwner(owner);
+        const ports = {
+            gracefulStop: async (target) => {
+                if (this.#tmux === undefined)
+                    return false;
+                const hostId = target.scope === "task" ? target.taskId : "operator";
+                try {
+                    this.#tmux.killRole(hostId, target.roleName);
+                }
+                catch {
+                    return this.#tmux.probeRoleStatus(hostId, target.roleName) === "exited";
+                }
+                return this.#tmux.probeRoleStatus(hostId, target.roleName) === "exited";
+            },
+            processIdentity: readLinuxProcessIdentity,
+            procEntryExists: (pid) => {
+                try {
+                    return existsSync(`/proc/${pid}`);
+                }
+                catch {
+                    return false;
+                }
+            },
+            listLaunchFencedProcesses: (launchId) => listLaunchFencedProcesses(launchId),
+            signalProcess: (pid, signal) => process.kill(pid, signal),
+            signalProcessGroup: (processGroupId, signal) => {
+                try {
+                    process.kill(-processGroupId, signal);
+                }
+                catch (error) {
+                    if (error.code !== "ESRCH")
+                        throw error;
+                }
+            },
+            sleep: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+            emit: (event) => this.#recordTerminationEvent(event),
+            now: () => new Date()
+        };
+        const result = await terminateSessionOwners(owner, records, ports, options);
+        if (result.outcome === "stop-confirmed") {
+            for (const record of result.confirmed) {
+                this.#store.removeSessionOwner(record.launchId);
+            }
+        }
+        return result;
+    }
+    #recordTerminationEvent(event) {
+        const owner = event.owner;
+        if (owner.scope !== "task")
+            return;
+        try {
+            this.#store.saveEvent(owner.taskId, createTaskEvent(this.#store.nextEventId(owner.taskId), owner.taskId, "runtime.session-termination", {
+                roleName: owner.roleName,
+                launchId: event.launchId ?? "",
+                nativeSessionId: event.nativeSessionId ?? "",
+                outcome: event.stage,
+                ...(event.detail === undefined ? {} : { detail: event.detail })
+            }, event.at));
+        }
+        catch (error) {
+            this.#onWarning(`Session termination event could not be persisted: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+/** Projects every durable Role session generation for reconciliation. */
+export function durableSessionFacts(store) {
+    const facts = [];
+    for (const task of store.listTasks()) {
+        for (const set of store.listRoleSessionSets(task.id)) {
+            for (const [agentId, session] of Object.entries(set.sessions)) {
+                facts.push({
+                    scope: "task",
+                    taskId: task.id,
+                    roleName: set.owner.roleName,
+                    agentId,
+                    adapterId: session.adapterId,
+                    ...(session.launchId === undefined ? {} : { launchId: session.launchId }),
+                    ...(session.nativeSessionId === undefined
+                        ? {}
+                        : { nativeSessionId: session.nativeSessionId }),
+                    status: session.status,
+                    inHistory: false
+                });
+            }
+            for (const history of set.history ?? []) {
+                facts.push({
+                    scope: "task",
+                    taskId: task.id,
+                    roleName: set.owner.roleName,
+                    agentId: history.agentId,
+                    adapterId: history.adapterId,
+                    ...(history.launchId === undefined ? {} : { launchId: history.launchId }),
+                    ...(history.nativeSessionId === undefined
+                        ? {}
+                        : { nativeSessionId: history.nativeSessionId }),
+                    status: history.status,
+                    inHistory: true
+                });
+            }
+        }
+    }
+    for (const set of store.listGlobalRoleSessionSets()) {
+        for (const [agentId, session] of Object.entries(set.sessions)) {
+            facts.push({
+                scope: "global",
+                roleName: set.owner.roleName,
+                agentId,
+                adapterId: session.adapterId,
+                ...(session.launchId === undefined ? {} : { launchId: session.launchId }),
+                ...(session.nativeSessionId === undefined
+                    ? {}
+                    : { nativeSessionId: session.nativeSessionId }),
+                status: session.status,
+                inHistory: false
+            });
+        }
+        const history = set.history;
+        for (const session of Object.values(history ?? {})) {
+            facts.push({
+                scope: "global",
+                roleName: set.owner.roleName,
+                agentId: session.agentId,
+                adapterId: session.adapterId,
+                ...(session.launchId === undefined ? {} : { launchId: session.launchId }),
+                ...(session.nativeSessionId === undefined
+                    ? {}
+                    : { nativeSessionId: session.nativeSessionId }),
+                status: session.status,
+                inHistory: true
+            });
+        }
+    }
+    return facts;
+}
+/** /proc observation for one owner record; undefined is a verification gap. */
+export function observeSessionOwnerPhysical(record) {
+    const { pid, startIdentity } = record.providerRoot;
+    const current = readLinuxProcessIdentity(pid);
+    if (current === undefined) {
+        return {
+            alive: false,
+            identityConflict: false,
+            pid,
+            startIdentity,
+            rssBytes: 0,
+            ageMs: 0,
+            childCount: 0
+        };
+    }
+    if (current.startIdentity !== startIdentity) {
+        // PID reuse: the slot is live but it is a different process. Never kill.
+        return {
+            alive: false,
+            identityConflict: true,
+            pid,
+            startIdentity,
+            rssBytes: current.rssBytes,
+            ageMs: 0,
+            childCount: 0
+        };
+    }
+    if (current.state === "Z") {
+        // Zombie: the process has exited and only the unreaped task struct
+        // remains. It cannot execute or hold resources, so it is not alive.
+        return {
+            alive: false,
+            identityConflict: false,
+            pid,
+            startIdentity,
+            rssBytes: 0,
+            ageMs: 0,
+            childCount: 0
+        };
+    }
+    const tree = listOwnedProcessTree(pid, current.processGroupId);
+    return {
+        alive: true,
+        identityConflict: false,
+        pid,
+        startIdentity,
+        rssBytes: current.rssBytes,
+        ageMs: 0,
+        childCount: Math.max(0, tree.length - 1)
+    };
+}
+/** Reads the latest termination outcome recorded for one generation. */
+export function lastSessionTerminationOutcome(store, taskId, roleName, launchId) {
+    if (taskId === undefined)
+        return undefined;
+    let latest;
+    for (const event of store.listEvents(taskId)) {
+        if (event.type !== "runtime.session-termination")
+            continue;
+        if (event.payload.roleName !== roleName)
+            continue;
+        if (launchId !== ""
+            && event.payload.launchId !== undefined
+            && event.payload.launchId !== ""
+            && event.payload.launchId !== launchId) {
+            continue;
+        }
+        latest = event.payload.outcome;
+    }
+    return latest;
+}
+/** True when one owner record's Provider root is still the exact live process. */
+export function ownerRootIsLive(record) {
+    return isLinuxProcessLive(record.providerRoot.pid, record.providerRoot.startIdentity);
+}
+/** Exact tmux target for one owner, for reports and diagnostics. */
+export function ownerTmuxTarget(home, owner) {
+    return yuiTmuxTarget(home, owner.scope === "task" ? owner.taskId : "operator", owner.roleName);
+}