@zq-silk/yui 0.2.0 → 0.4.2

package/dist/controller/providerHookRunFence.js

@@ -0,0 +1,127 @@
+import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
+import { hasRuntimeCleanupObligation, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
+import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
+/**
+ * Resolves turn identity from the current durable in-flight fence. The one
+ * exception is Claude SessionStart(startup), which can arrive synchronously
+ * before Session projection and is fenced by the exact Run-bound launch
+ * reservation plus deterministic native identity. The immutable hook event is
+ * revalidated by the normal inbox fold before changing any state.
+ */
+export function resolveProviderHookRunFence(environment, adapterId, payloadNativeSessionId, options = {}) {
+    if (environment.YUI_SESSION_SCOPE !== "task") {
+        throw new Error("Provider lifecycle hook requires a Task session scope.");
+    }
+    if (environment.YUI_ADAPTER_ID !== adapterId) {
+        throw new Error(`Provider lifecycle hook requires the ${adapterId} adapter.`);
+    }
+    const home = requireIdentity(environment.YUI_HOME, "YUI_HOME");
+    const taskId = requireIdentity(environment.YUI_TASK_ID, "Task id");
+    const roleName = requireIdentity(environment.YUI_ROLE, "Role name");
+    const agentId = requireIdentity(environment.YUI_AGENT_ID, "Agent id");
+    const workspace = requireIdentity(environment.YUI_WORKSPACE, "YUI workspace");
+    const launchId = requireIdentity(environment.YUI_LAUNCH_ID, "Launch id");
+    const nativeSessionId = requireIdentity(payloadNativeSessionId, "Provider session id");
+    const expectedNativeSessionId = environment.YUI_NATIVE_SESSION_ID;
+    if (expectedNativeSessionId !== undefined
+        && nativeSessionId !== requireIdentity(expectedNativeSessionId, "YUI native session id")) {
+        throw new Error("Provider lifecycle hook native session does not match its launch envelope.");
+    }
+    const store = openCompatibleFileTaskStore(home);
+    const task = store.getTask(taskId);
+    if (task === null || task.status !== "active") {
+        throw new Error("Provider lifecycle hook Task is not current and active.");
+    }
+    const role = store.getRole(taskId, roleName);
+    if (role === null || role.activeAgentId !== agentId) {
+        throw new Error("Provider lifecycle hook Role or Agent is not current.");
+    }
+    const sessions = store.getTaskRoleSessionSet(taskId, roleName);
+    if (sessions !== null && sessions.activeAgentId !== agentId) {
+        throw new Error("Provider lifecycle hook Session Agent is not current.");
+    }
+    const inFlight = sessions?.inFlight;
+    const session = sessions?.sessions[agentId];
+    const mailbox = store.getWorkMailbox(runtimeLifecycleTarget({
+        scope: "task",
+        taskId,
+        roleName
+    }));
+    const exactReservation = isRuntimeLaunchReservation(mailbox?.processing, launchId)
+        && !hasRuntimeCleanupObligation(mailbox);
+    const executionRef = mailbox?.processing?.executionRef;
+    const startupRunId = options.allowPreallocatedClaudeStartup === true
+        ? requireIdentity(environment.YUI_RUN_ID, "Run id")
+        : undefined;
+    const deterministicClaudeStartup = adapterId === "claude"
+        && options.allowPreallocatedClaudeStartup === true
+        && expectedNativeSessionId !== undefined
+        && session === undefined
+        && exactReservation
+        && executionRef?.type === "run"
+        && executionRef.taskId === taskId
+        && executionRef.id === startupRunId
+        && nativeSessionId === nativeSessionIdForLaunch(home, launchId, agentId, adapterId);
+    if ((inFlight === null || inFlight === undefined) && !deterministicClaudeStartup) {
+        throw new Error("Provider lifecycle hook has no matching durable in-flight Run.");
+    }
+    if (inFlight !== null && inFlight !== undefined && inFlight.agentId !== agentId) {
+        throw new Error("Provider lifecycle hook has no matching durable in-flight Run.");
+    }
+    if (deterministicClaudeStartup
+        && inFlight !== null
+        && inFlight !== undefined
+        && (inFlight.runId !== startupRunId
+            || inFlight.receiptId !== formatAgentRunReceiptId(taskId, startupRunId))) {
+        throw new Error("Provider lifecycle hook has no matching durable in-flight Run.");
+    }
+    const runId = inFlight?.runId ?? startupRunId;
+    const run = store.getActiveAgentRun(taskId, roleName);
+    if (run === null
+        || run.id !== runId
+        || run.status !== "active"
+        || run.effective.agentId !== agentId
+        || run.effective.adapterId !== adapterId) {
+        throw new Error("Provider lifecycle hook Run does not match durable active state.");
+    }
+    if (run.effective.workspace.root !== workspace) {
+        throw new Error("Provider lifecycle hook workspace does not match the durable Run snapshot.");
+    }
+    if (session !== undefined) {
+        if (session.adapterId !== adapterId
+            || session.launchId !== launchId
+            || session.nativeSessionId !== nativeSessionId
+            || session.effective.workspace.root !== workspace) {
+            throw new Error("Provider lifecycle hook Session does not match its durable generation.");
+        }
+    }
+    else {
+        const runtimeDiscoveredCodex = adapterId === "codex"
+            && expectedNativeSessionId === undefined
+            && exactReservation;
+        if (!runtimeDiscoveredCodex && !deterministicClaudeStartup) {
+            throw new Error("Provider lifecycle hook launch is not durably reserved.");
+        }
+    }
+    return {
+        taskId,
+        roleName,
+        agentId,
+        launchId,
+        runId,
+        ...(inFlight?.receiptId === undefined ? {} : { receiptId: inFlight.receiptId }),
+        nativeSessionId,
+        workspace
+    };
+}
+function requireIdentity(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is required.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.length > 1_024) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}

package/dist/controller/resourceCleanupLinux.js

@@ -0,0 +1,286 @@
+import { lstatSync, readFileSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { NodeCommandExecutor } from "../tmux/commandExecutor.js";
+import { TmuxManager } from "../tmux/tmuxManager.js";
+import { controllerSocketPath } from "../core/controllerEndpoint.js";
+import { CONTROLLER_DOMAIN_PATH, domainIdentityPath, removeEphemeralDomainIdentityIfUnchanged, readEphemeralDomainIdentity, withEphemeralDomainIdentityCleanupEpoch } from "./domainIdentity.js";
+const DEFAULT_TERM_GRACE_MS = 1_000;
+const DEFAULT_KILL_GRACE_MS = 1_000;
+const DEFAULT_POLL_MS = 50;
+export async function cleanControllerResource(resource, options = {}) {
+    if (resource.disposition !== "safe" && resource.disposition !== "review") {
+        throw new Error(`Resource is not eligible for cleanup: ${resource.id}.`);
+    }
+    assertEphemeralDomainFence(resource);
+    const environment = options.environment ?? process.env;
+    const ports = options.ports ?? linuxCleanupPorts(environment);
+    const cleanup = async () => {
+        if (resource.artifact !== undefined) {
+            cleanArtifact(resource, ports);
+            return;
+        }
+        if (resource.kind === "agent-session") {
+            assertProcessIdentities(resource, ports);
+            await ports.killPane(resource);
+            return;
+        }
+        if (resource.processes.length === 0) {
+            throw new Error(`Resource has no cleanup target: ${resource.id}.`);
+        }
+        if (resource.kind === "tmux-server") {
+            const panes = await ports.inspectTmuxServerPanes(resource);
+            if (panes.length > 0) {
+                throw new Error(`Tmux server still owns Role panes: ${panes.join(", ")}.`);
+            }
+            // Close the small inspect-to-signal race without inventing a wait or
+            // broad process-name rule. A target appearing on the second exact query
+            // keeps the server protected for the next bounded pass.
+            const recheckedPanes = await ports.inspectTmuxServerPanes(resource);
+            if (recheckedPanes.length > 0) {
+                throw new Error(`Tmux server still owns Role panes: ${recheckedPanes.join(", ")}.`);
+            }
+        }
+        assertProcessIdentities(resource, ports);
+        for (const process of [...resource.processes].reverse()) {
+            signalIfOwned(process.pid, process.startIdentity, "SIGTERM", ports);
+        }
+        const termGraceMs = positiveDuration(options.termGraceMs, DEFAULT_TERM_GRACE_MS, "termGraceMs");
+        const killGraceMs = positiveDuration(options.killGraceMs, DEFAULT_KILL_GRACE_MS, "killGraceMs");
+        const pollMs = positiveDuration(options.pollMs, DEFAULT_POLL_MS, "pollMs");
+        await waitForProcesses(resource, ports, termGraceMs, pollMs);
+        for (const process of [...resource.processes].reverse()) {
+            signalIfOwned(process.pid, process.startIdentity, "SIGKILL", ports);
+        }
+        await waitForProcesses(resource, ports, killGraceMs, pollMs);
+        const remaining = resource.processes.filter((process) => (ports.processStartIdentity(process.pid) === process.startIdentity));
+        if (remaining.length > 0) {
+            throw new Error(`Resource processes did not stop: ${remaining.map(({ pid }) => pid).join(", ")}.`);
+        }
+    };
+    const domain = resource.domain;
+    if (resource.artifact === undefined
+        && domain?.kind === "ephemeral-test") {
+        const home = resource.yuiHome;
+        const token = domain.token;
+        if (home === undefined || token === undefined) {
+            throw new Error(`Ephemeral domain identity is unavailable: ${resource.id}.`);
+        }
+        ports.beforeDomainCleanupEpoch?.(resource);
+        const epoch = await withEphemeralDomainIdentityCleanupEpoch(home, token, domain.fingerprint, cleanup);
+        if (epoch !== "completed") {
+            throw new Error(`Resource changed since scan: ${resource.id}.`);
+        }
+        return;
+    }
+    await cleanup();
+}
+function assertEphemeralDomainFence(resource) {
+    const domain = resource.domain;
+    if (domain?.kind !== "ephemeral-test")
+        return;
+    const home = resource.yuiHome;
+    if (home === undefined || domain.token === undefined) {
+        throw new Error(`Ephemeral domain identity is unavailable: ${resource.id}.`);
+    }
+    const identity = readEphemeralDomainIdentity(home);
+    if (identity.status !== "valid" || identity.identity?.token !== domain.token) {
+        throw new Error(`Resource changed since scan: ${resource.id}.`);
+    }
+}
+function cleanArtifact(resource, ports) {
+    const artifact = resource.artifact;
+    if (artifact === undefined)
+        throw new Error(`Artifact is unavailable: ${resource.id}.`);
+    assertOwnedArtifactPath(resource);
+    const currentFingerprint = ports.artifactFingerprint(artifact.path);
+    // A concurrent exact cleanup may have already removed this artifact. The
+    // desired state is still satisfied; only a changed live inode is ambiguous.
+    if (currentFingerprint === undefined)
+        return;
+    if (currentFingerprint !== artifact.fingerprint) {
+        throw new Error(`Resource changed since scan: ${resource.id}.`);
+    }
+    if (artifact.artifactKind === "domain-identity") {
+        const home = resource.yuiHome;
+        const expectedToken = resource.domain?.token;
+        if (home === undefined || expectedToken === undefined) {
+            throw new Error(`Ephemeral domain identity is unavailable: ${resource.id}.`);
+        }
+        const removal = removeEphemeralDomainIdentityIfUnchanged(home, expectedToken, artifact.fingerprint);
+        if (removal === "absent")
+            return;
+        if (removal !== "removed") {
+            throw new Error(`Resource changed since scan: ${resource.id}.`);
+        }
+        return;
+    }
+    if (artifact.artifactKind.endsWith("-socket")
+        && ports.socketActive(artifact.path)) {
+        throw new Error(`Resource socket is active: ${artifact.path}.`);
+    }
+    ports.removeArtifact(artifact.path);
+}
+function assertProcessIdentities(resource, ports) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    for (const candidate of resource.processes) {
+        if (candidate.pid <= 1
+            || candidate.pid === process.pid
+            || candidate.uid !== uid
+            || ports.processStartIdentity(candidate.pid) !== candidate.startIdentity) {
+            throw new Error(`Resource changed since scan: ${resource.id}.`);
+        }
+    }
+}
+function signalIfOwned(pid, startIdentity, signal, ports) {
+    if (ports.processStartIdentity(pid) !== startIdentity)
+        return;
+    try {
+        ports.signal(pid, signal);
+    }
+    catch (error) {
+        if (!isMissingProcess(error))
+            throw error;
+    }
+}
+async function waitForProcesses(resource, ports, graceMs, pollMs) {
+    for (let elapsed = 0; elapsed < graceMs; elapsed += pollMs) {
+        if (resource.processes.every((candidate) => (ports.processStartIdentity(candidate.pid) !== candidate.startIdentity))) {
+            return;
+        }
+        await ports.sleep(Math.min(pollMs, graceMs - elapsed));
+    }
+}
+function linuxCleanupPorts(environment) {
+    return {
+        processStartIdentity: readProcessStartIdentity,
+        signal: (pid, signal) => process.kill(pid, signal),
+        sleep: (milliseconds) => new Promise((resolveSleep) => {
+            setTimeout(resolveSleep, milliseconds);
+        }),
+        artifactFingerprint: (path) => {
+            try {
+                return statFingerprint(lstatSync(path));
+            }
+            catch {
+                return undefined;
+            }
+        },
+        socketActive: unixSocketIsActive,
+        removeArtifact: (path) => unlinkSync(path),
+        inspectTmuxServerPanes: async (resource) => {
+            const manager = tmuxManagerForResource(resource, environment);
+            return manager.inspectRolePaneInventory().map((pane) => (`${pane.taskId}/${pane.roleName}`));
+        },
+        killPane: async (resource) => {
+            const target = resource.target;
+            if (target === undefined) {
+                throw new Error(`Role pane identity is unavailable: ${resource.id}.`);
+            }
+            const manager = tmuxManagerForResource(resource, environment);
+            const pane = manager.inspectRolePaneInventory().find((candidate) => (candidate.target === target));
+            if (pane === undefined)
+                return;
+            if (resource.paneDead !== undefined
+                && pane.dead !== resource.paneDead) {
+                throw new Error(`Resource changed since scan: ${resource.id}.`);
+            }
+            if (resource.paneCommand !== undefined
+                && pane.currentCommand !== resource.paneCommand) {
+                throw new Error(`Resource changed since scan: ${resource.id}.`);
+            }
+            const expectedPid = resource.processes[0]?.pid;
+            if (expectedPid !== undefined && pane.pid !== expectedPid) {
+                throw new Error(`Resource changed since scan: ${resource.id}.`);
+            }
+            manager.killRole(pane.taskId, pane.roleName);
+            if (manager.inspectRolePaneInventory().some((candidate) => candidate.target === target)) {
+                throw new Error(`Role pane did not stop: ${target}.`);
+            }
+        }
+    };
+}
+function tmuxManagerForResource(resource, environment) {
+    const home = resource.yuiHome;
+    if (home === undefined) {
+        throw new Error(`Tmux resource home is unavailable: ${resource.id}.`);
+    }
+    return new TmuxManager(environment.YUI_TMUX_BIN ?? "tmux", new NodeCommandExecutor(), { yuiHome: home });
+}
+function readProcessStartIdentity(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const closing = stat.lastIndexOf(")");
+        if (closing < 0)
+            return undefined;
+        const identity = stat.slice(closing + 1).trim().split(/\s+/u)[19];
+        return identity !== undefined && /^[0-9]{1,32}$/u.test(identity)
+            ? identity
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function unixSocketIsActive(expectedPath) {
+    try {
+        return readFileSync("/proc/net/unix", "utf8").split("\n").slice(1)
+            .some((line) => line.trim().split(/\s+/u)[7] === expectedPath);
+    }
+    catch {
+        // Without a liveness proof, refuse socket deletion.
+        return true;
+    }
+}
+function assertOwnedArtifactPath(resource) {
+    const artifact = resource.artifact;
+    if (artifact === undefined)
+        throw new Error(`Artifact is unavailable: ${resource.id}.`);
+    const uid = typeof process.getuid === "function" ? process.getuid() : 0;
+    const path = resolve(artifact.path);
+    if (artifact.artifactKind === "tmux-socket") {
+        const directory = join(tmpdir(), `tmux-${uid}`);
+        if (dirname(path) !== directory
+            || !/^yui-[a-f0-9]{24}$/u.test(basename(path))) {
+            throw new Error(`Artifact path is outside the Yui tmux namespace: ${path}.`);
+        }
+        return;
+    }
+    const home = resource.yuiHome;
+    if (home !== undefined
+        && artifact.artifactKind === "controller-socket"
+        && path === controllerSocketPath(home)) {
+        return;
+    }
+    if (home !== undefined
+        && artifact.artifactKind === "domain-identity"
+        && path === domainIdentityPath(home)
+        && basename(path) === basename(join(resolve(home), CONTROLLER_DOMAIN_PATH))) {
+        return;
+    }
+    if (home === undefined
+        || dirname(path) !== join(resolve(home), "runtime")
+        || !/^controller\.(?:json|sock)$/u.test(basename(path))) {
+        throw new Error(`Artifact path is outside the Yui Controller namespace: ${path}.`);
+    }
+}
+function statFingerprint(metadata) {
+    return [
+        metadata.dev,
+        metadata.ino,
+        metadata.mode,
+        metadata.size,
+        Math.trunc(metadata.mtimeMs)
+    ].join(":");
+}
+function positiveDuration(value, fallback, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new TypeError(`${label} must be a positive integer.`);
+    }
+    return resolved;
+}
+function isMissingProcess(error) {
+    return error instanceof Error && "code" in error
+        && error.code === "ESRCH";
+}