@zq-silk/yui 0.6.0 → 0.6.2

package/dist/controller/jobSupervisor.js

@@ -0,0 +1,498 @@
+/**
+ * DurableJob supervision: the Controller-side reconciliation ladder.
+ *
+ * The supervisor is pure logic over injected ports. It is invoked from the
+ * Controller scheduler pass and on Controller startup. Each pass reconciles
+ * every job toward its correct state:
+ *
+ *  queued  -> write spec, spawn detached runner, transition to running
+ *  running -> harvest exit.json / liveness via pid+startIdentity /
+ *             evidence ladder (exit.json -> checkpoint -> unknown) /
+ *             stale heartbeat SIGTERM then SIGKILL escalation
+ *  terminal + !wakeupNotified -> set flag + enqueue Leader wakeup
+ *  cancelRequestedAt -> write cancel fence + SIGTERM
+ */
+import { spawn } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeTextFileAtomically } from "../storage/durableFile.js";
+import { cancelQueuedDurableJob, completeDurableJob, isDurableJobTerminal, markDurableJobUnknown, markDurableJobWakeupNotified, startDurableJob, touchDurableJobHeartbeat } from "../job/durableJob.js";
+import { readLinuxProcessStartIdentity } from "./domainIdentity.js";
+const DEFAULT_STEP_TIMEOUT_MS = 30 * 60_000;
+const HEARTBEAT_STALE_MS = 2 * 60_000;
+const SIGKILL_GRACE_MS = 30_000;
+export class DurableJobSupervisor {
+    #store;
+    #process;
+    #artifacts;
+    #terminalEvents;
+    #wake;
+    #onError;
+    // f5: Composite key (taskId/jobId) because job IDs are Task-local — every
+    // Task has a job-1, so a Task-local key would cross-kill healthy runners.
+    #sigkillAt = new Map();
+    constructor(options) {
+        this.#store = options.store;
+        this.#process = options.process;
+        this.#artifacts = options.artifacts;
+        this.#terminalEvents = options.terminalEvents;
+        this.#wake = options.wake ?? (() => undefined);
+        this.#onError = options.onError ?? (() => undefined);
+    }
+    reconcile(now) {
+        const jobs = this.#store.listAllDurableJobs();
+        for (const job of jobs) {
+            try {
+                this.#reconcileJob(job, now);
+            }
+            catch (error) {
+                this.#onError(error instanceof Error
+                    ? error
+                    : new Error(`DurableJob supervision failed for ${job.id}: ${String(error)}`));
+            }
+        }
+    }
+    #reconcileJob(job, now) {
+        if (job.status === "queued") {
+            this.#reconcileQueued(job, now);
+            return;
+        }
+        if (job.status === "running") {
+            this.#superviseRunning(job, now);
+            return;
+        }
+        if (isDurableJobTerminal(job.status) && job.wakeupNotified !== true) {
+            this.#notifyWakeup(job, now);
+        }
+    }
+    /** Composite key for the SIGKILL deadline map. */
+    #sigkillKey(job) {
+        return `${job.taskId}/${job.id}`;
+    }
+    /**
+     * Reconcile a queued job.
+     *
+     * f4: A queued job with a cancel request converges to `cancelled` without
+     * spawning a runner — but only if no runner was already spawned. If a
+     * start marker proves a runner exists (real pid, or pending marker +
+     * ready.json), the job is adopted to running first; the running-cancel
+     * path then fences and signals it. Cancelling a spawned job from queued
+     * would orphan the runner.
+     *
+     * f3: The normal path writes a pending start marker, spawns the runner, and
+     * lets the runner's own `ready.json` handshake prove it started before any
+     * side effect. On recovery the supervisor adopts queued→running first
+     * (harvest/unknown require `running`), then harvests exit or handles a
+     * dead process — never calling complete/unknown directly from `queued`.
+     */
+    #reconcileQueued(job, now) {
+        const marker = this.#artifacts.readStartMarker(job.taskId, job.id);
+        // f1/rr5: A cancel request on a queued job must not orphan an already-
+        // spawned runner. Check spawn evidence before converging to cancelled.
+        if (job.cancelRequestedAt !== undefined) {
+            this.#artifacts.writeCancelFence(job.taskId, job.id);
+            const spawnedProcess = this.#spawnedProcessFromEvidence(job, marker);
+            if (spawnedProcess !== null) {
+                // f1/rr5: A runner was spawned. Signal it in THIS reconcile pass —
+                // not adopt to running and wait for the next pass. The signal is
+                // sent before the adoption so the runner begins draining
+                // immediately; the adoption preserves evidence (exit.json / dead-
+                // process handling converges the job on this or the next pass).
+                this.#process.signalIfOwned(spawnedProcess.pid, spawnedProcess.startIdentity, "SIGTERM");
+                this.#adoptAndContinue(job, spawnedProcess, now);
+                return;
+            }
+            if (marker !== null) {
+                // f1/rr5: Ambiguous spawn — a pending marker exists but ready.json
+                // does not. The runner may be starting (slow to write ready.json)
+                // or may never have started. Do NOT terminalize without signaling.
+                // Re-spawn: the new runner writes ready.json, observes the cancel
+                // fence, and exits as cancelled without side effects. The next
+                // pass harvests the cancelled exit.json.
+                this.#startJob(job, now);
+                return;
+            }
+            // No spawn attempted — safe to cancel from queued.
+            // f6/rr5: The terminal transition and the Leader wakeup must be
+            // atomic (same transaction). Compose cancel + wakeupNotified and
+            // pass the wakeup param so the adapter enqueues the Leader mailbox
+            // entry in the same transaction.
+            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(cancelQueuedDurableJob(current, now), now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+            this.#deliverTerminalEvent(terminal);
+            return;
+        }
+        if (marker === null) {
+            this.#startJob(job, now);
+            return;
+        }
+        // f3: A pending marker means the Controller died after writing the marker
+        // but before the runner proved it started. Check the runner's ready file.
+        if (marker.startIdentity === "pending") {
+            const ready = this.#artifacts.readReadyFile(job.taskId, job.id);
+            if (ready === null) {
+                // The runner either never started or died before writing ready.
+                // No side effects could have occurred — re-spawn safely.
+                this.#startJob(job, now);
+                return;
+            }
+            // Runner proved it started: adopt and continue from evidence.
+            // rr4/finding-4: Use the runner's own startIdentity from ready.json,
+            // not a fresh /proc read (which could return a reused PID's identity).
+            this.#adoptAndContinue(job, { pid: ready.pid, startIdentity: ready.startIdentity }, now);
+            return;
+        }
+        // Marker with a real pid (already spawned). Adopt and continue.
+        // f3/rr5: ready.json is authoritative when both exist.
+        const spawned = this.#spawnedProcessFromEvidence(job, marker);
+        this.#adoptAndContinue(job, spawned ?? { pid: marker.pid, startIdentity: marker.startIdentity }, now);
+    }
+    /**
+     * Determine whether a runner was spawned for this job, based on durable
+     * evidence. Returns the process identity if spawned, null otherwise.
+     */
+    #spawnedProcessFromEvidence(job, marker) {
+        if (marker === null)
+            return null;
+        // f3/rr5: ready.json is the runner's own record of its actual OS start.
+        // When both the start marker and ready.json exist, ready.json is
+        // authoritative: the marker is the Controller's declared intent (written
+        // around the spawn), while ready.json is written by the runner itself
+        // before any side effect. A disagreement (PID reuse, spawn retry, stale
+        // /proc read) is resolved in favor of ready.json.
+        const ready = this.#artifacts.readReadyFile(job.taskId, job.id);
+        if (ready !== null) {
+            return { pid: ready.pid, startIdentity: ready.startIdentity };
+        }
+        if (marker.startIdentity !== "pending") {
+            // Real start marker with a pid — the runner was spawned.
+            return { pid: marker.pid, startIdentity: marker.startIdentity };
+        }
+        // Pending marker with no ready.json: spawn unconfirmed.
+        return null;
+    }
+    /**
+     * f3: Adopt a queued job to running, then harvest exit or handle a dead
+     * process. This is the only legal path from queued to a terminal state —
+     * complete/unknown require `running`.
+     */
+    #adoptAndContinue(job, process, now) {
+        this.#store.transitionDurableJob(job.taskId, job.id, (current) => startDurableJob(current, process, now), now);
+        // The runner may already have finished while the Controller was down.
+        const exit = this.#artifacts.readExitJson(job.taskId, job.id);
+        if (exit !== null) {
+            this.#harvestExit(job, exit, now);
+            return;
+        }
+        const identity = this.#process.processStartIdentity(process.pid);
+        const alive = identity !== undefined
+            && identity === process.startIdentity
+            && this.#process.isProcessAlive(process.pid);
+        if (!alive) {
+            this.#handleDeadProcess(job, now);
+        }
+    }
+    #startJob(job, now) {
+        const spec = {
+            jobId: job.id,
+            taskId: job.taskId,
+            workspace: job.workspace,
+            env: job.env,
+            steps: job.steps,
+            defaultStepTimeoutMs: DEFAULT_STEP_TIMEOUT_MS,
+            artifactDir: this.#artifacts.artifactDir(job.taskId, job.id),
+            head: job.head
+        };
+        const specPath = this.#artifacts.writeSpec(job.taskId, job.id, spec);
+        // f3: Write a pending start marker BEFORE spawning. If the Controller dies
+        // between this write and the spawn, the next pass sees the pending marker
+        // and re-spawns safely (no side effects without a ready file).
+        this.#artifacts.writeStartMarker(job.taskId, job.id, {
+            pid: 0,
+            startIdentity: "pending",
+            spawnedAt: now.toISOString()
+        });
+        const spawned = this.#process.spawnJobRunner(specPath);
+        // Best-effort update with the real pid. If this fails (Controller death),
+        // the runner's own ready.json is the fallback: the next reconcile reads
+        // ready and adopts. The runner checks ready with O_EXCL and exits if it
+        // already exists, preventing duplicate execution.
+        this.#artifacts.writeStartMarker(job.taskId, job.id, {
+            pid: spawned.pid,
+            startIdentity: spawned.startIdentity ?? String(spawned.pid),
+            spawnedAt: now.toISOString()
+        });
+        // rr6/f1: Bound the supervision latency without a busy loop. One follow-up
+        // pass adopts the queued job to running (the real-pid marker path above),
+        // and the runner-exit callback schedules the harvest pass while the
+        // Controller lives. Both are idempotent no-ops if the job already
+        // terminalized or no longer exists; the recovery interval stays the
+        // cross-restart fallback. No new timer is pinned while the Controller is
+        // idle — each wake is a single event-driven signal.
+        spawned.onExit?.(() => this.#wake(job.taskId));
+        this.#wake(job.taskId);
+    }
+    #superviseRunning(job, now) {
+        // 1. Harvest exit.json if present.
+        const exit = this.#artifacts.readExitJson(job.taskId, job.id);
+        if (exit !== null) {
+            this.#harvestExit(job, exit, now);
+            return;
+        }
+        // 2. Cancel requested: write fence + SIGTERM.
+        if (job.cancelRequestedAt !== undefined && job.process !== undefined) {
+            this.#artifacts.writeCancelFence(job.taskId, job.id);
+            this.#process.signalIfOwned(job.process.pid, job.process.startIdentity, "SIGTERM");
+        }
+        // 3. Process liveness via pid + startIdentity.
+        if (job.process !== undefined) {
+            const identity = this.#process.processStartIdentity(job.process.pid);
+            const alive = identity !== undefined
+                && identity === job.process.startIdentity
+                && this.#process.isProcessAlive(job.process.pid);
+            if (!alive) {
+                this.#handleDeadProcess(job, now);
+                return;
+            }
+        }
+        // 4. Heartbeat freshness.
+        const heartbeatMtime = this.#artifacts.heartbeatMtime(job.taskId, job.id);
+        if (heartbeatMtime !== null) {
+            const staleMs = now.getTime() - heartbeatMtime;
+            if (staleMs > HEARTBEAT_STALE_MS && job.process !== undefined) {
+                this.#process.signalIfOwned(job.process.pid, job.process.startIdentity, "SIGTERM");
+                const existing = this.#sigkillAt.get(this.#sigkillKey(job));
+                if (existing === undefined) {
+                    this.#sigkillAt.set(this.#sigkillKey(job), now.getTime() + SIGKILL_GRACE_MS);
+                }
+            }
+            const recordHeartbeat = job.heartbeatAt !== undefined
+                ? Date.parse(job.heartbeatAt)
+                : 0;
+            if (heartbeatMtime > recordHeartbeat) {
+                this.#store.transitionDurableJob(job.taskId, job.id, (current) => touchDurableJobHeartbeat(current, new Date(heartbeatMtime)), now);
+            }
+        }
+        // 5. SIGKILL escalation.
+        const sigkillAt = this.#sigkillAt.get(this.#sigkillKey(job));
+        if (sigkillAt !== undefined && now.getTime() >= sigkillAt && job.process !== undefined) {
+            this.#process.signalIfOwned(job.process.pid, job.process.startIdentity, "SIGKILL");
+            this.#sigkillAt.delete(this.#sigkillKey(job));
+        }
+    }
+    #harvestExit(job, exit, now) {
+        const result = {
+            outcome: exit.outcome,
+            exitCode: exit.exitCode,
+            signal: exit.signal,
+            ...(exit.failedStep === undefined ? {} : { failedStep: exit.failedStep }),
+            evidenceSource: "exit-artifact",
+            steps: exit.steps
+        };
+        // rr4/finding-7: The terminal transition and the Leader wakeup must be
+        // atomic. Compose complete + wakeupNotified and pass the wakeup param so
+        // the adapter enqueues the Leader mailbox entry in the same transaction.
+        // A separate #notifyWakeup pass would lose the wakeup if the Controller
+        // died between the terminal write and the flag flip.
+        const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, result, now), now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+        this.#deliverTerminalEvent(terminal);
+        this.#sigkillAt.delete(this.#sigkillKey(job));
+    }
+    #handleDeadProcess(job, now) {
+        const checkpoint = this.#artifacts.readCheckpoint(job.taskId, job.id);
+        const proven = checkpoint === null ? null : proveOutcomeFromCheckpoint(job, checkpoint);
+        // rr4/finding-7: Same atomic wakeup composition as #harvestExit — the
+        // terminal transition and the Leader wakeup commit together.
+        if (proven !== null) {
+            // The runner died without exit.json, but its step checkpoint covered
+            // every planned step: the outcome is still provable from durable
+            // evidence. No false pass — the checkpoint is the runner's own record.
+            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, { ...proven, evidenceSource: "checkpoint" }, now), now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+            this.#deliverTerminalEvent(terminal);
+        }
+        else {
+            const completedSteps = checkpoint?.completedSteps ?? [];
+            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(markDurableJobUnknown(current, "runner process exited without writing exit.json", completedSteps, now), now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+            this.#deliverTerminalEvent(terminal);
+        }
+        this.#sigkillAt.delete(this.#sigkillKey(job));
+    }
+    /**
+     * f7/rr5: Deliver a terminal notice to the runtime inbox channel when a
+     * Job reaches a terminal state. The notice is best-effort: the terminal
+     * transition already committed, so a delivery failure must not fail the
+     * reconcile pass. The composition root wires this to the runtime event
+     * inbox so the Controller wakes immediately instead of waiting for the
+     * next poll.
+     */
+    #deliverTerminalEvent(job) {
+        if (job === null || !isDurableJobTerminal(job.status))
+            return;
+        this.#terminalEvents?.deliverTerminalEvent({
+            taskId: job.taskId,
+            jobId: job.id,
+            status: job.status,
+            outcome: job.result?.outcome ?? job.status
+        });
+    }
+    /**
+     * Recovery fallback for terminal jobs that reached their terminal state
+     * before the atomic wakeup composition existed (or whose wakeup was lost).
+     * The normal path (#harvestExit / #handleDeadProcess) already composes
+     * complete + wakeupNotified + enqueue in one transaction; this pass only
+     * fires for jobs that somehow slipped through without wakeupNotified.
+     */
+    #notifyWakeup(job, now) {
+        this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(current, now), now, { reason: "job-finished", refs: wakeupRefs(job) });
+    }
+}
+function wakeupRefs(job) {
+    const refs = [{ type: "task", id: job.taskId }];
+    if (job.owner.kind === "work-item") {
+        refs.push({ type: "work-item", taskId: job.taskId, id: job.owner.workItemId });
+    }
+    return refs;
+}
+/**
+ * Prove a terminal outcome from the step checkpoint when the runner died
+ * without writing exit.json. Returns null (fail closed → unknown) unless the
+ * checkpoint covers every planned step exactly, by name.
+ */
+function proveOutcomeFromCheckpoint(job, checkpoint) {
+    const byName = new Map(checkpoint.completedSteps.map((step) => [step.name, step]));
+    if (byName.size !== checkpoint.completedSteps.length)
+        return null;
+    if (byName.size !== job.steps.length)
+        return null;
+    const ordered = [];
+    for (const planned of job.steps) {
+        const step = byName.get(planned.name);
+        if (step === undefined)
+            return null;
+        ordered.push(step);
+    }
+    const failing = ordered.find((step) => step.timedOut || step.exitCode !== 0 || step.signal !== null);
+    if (failing === undefined) {
+        return { outcome: "succeeded", exitCode: 0, signal: null, steps: ordered };
+    }
+    if (failing.timedOut) {
+        return {
+            outcome: "timed-out",
+            exitCode: failing.exitCode,
+            signal: failing.signal,
+            failedStep: failing.name,
+            steps: ordered
+        };
+    }
+    return {
+        outcome: "failed",
+        exitCode: failing.exitCode,
+        signal: failing.signal,
+        failedStep: failing.name,
+        steps: ordered
+    };
+}
+// ---------------------------------------------------------------------------
+// Production ports
+// ---------------------------------------------------------------------------
+export function createLinuxProcessPort() {
+    return {
+        spawnJobRunner(specPath) {
+            const child = spawn(process.execPath, [fileURLToPath(new URL("../job/jobRunner.js", import.meta.url)), specPath], { detached: true, stdio: "ignore" });
+            child.unref();
+            const startIdentity = readLinuxProcessStartIdentity(child.pid);
+            return {
+                pid: child.pid,
+                startIdentity,
+                // rr6/f1: Wake the supervisor when the runner exits so the Controller
+                // harvests the terminal artifact immediately. The listener does not
+                // re-ref the child (unref already detached the event-loop hold), so it
+                // cannot pin the Controller; if the Controller dies first, the
+                // recovery interval remains the fallback.
+                onExit: (callback) => {
+                    child.on("exit", () => callback());
+                }
+            };
+        },
+        processStartIdentity(pid) {
+            return readLinuxProcessStartIdentity(pid);
+        },
+        isProcessAlive(pid) {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch (error) {
+                return error.code !== "ESRCH";
+            }
+        },
+        signalIfOwned(pid, startIdentity, signal) {
+            if (readLinuxProcessStartIdentity(pid) !== startIdentity)
+                return;
+            try {
+                process.kill(pid, signal);
+            }
+            catch (error) {
+                if (error.code !== "ESRCH")
+                    throw error;
+            }
+        }
+    };
+}
+export function createFileArtifactPort(home) {
+    return {
+        artifactDir(taskId, jobId) {
+            return join(home, "artifacts", "jobs", taskId, jobId);
+        },
+        writeSpec(taskId, jobId, spec) {
+            const dir = join(home, "artifacts", "jobs", taskId, jobId);
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            chmodSync(dir, 0o700);
+            const specPath = join(dir, "spec.json");
+            writeTextFileAtomically(specPath, `${JSON.stringify(spec, null, 2)}\n`);
+            return specPath;
+        },
+        writeCancelFence(taskId, jobId) {
+            const dir = join(home, "artifacts", "jobs", taskId, jobId);
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            const fencePath = join(dir, "cancel");
+            if (!existsSync(fencePath)) {
+                const fd = openSync(fencePath, "w", 0o600);
+                closeSync(fd);
+            }
+        },
+        readExitJson(taskId, jobId) {
+            return readJsonFile(join(home, "artifacts", "jobs", taskId, jobId, "exit.json"));
+        },
+        readCheckpoint(taskId, jobId) {
+            return readJsonFile(join(home, "artifacts", "jobs", taskId, jobId, "checkpoint.json"));
+        },
+        heartbeatMtime(taskId, jobId) {
+            try {
+                return statSync(join(home, "artifacts", "jobs", taskId, jobId, "heartbeat")).mtimeMs;
+            }
+            catch {
+                return null;
+            }
+        },
+        writeStartMarker(taskId, jobId, marker) {
+            const dir = join(home, "artifacts", "jobs", taskId, jobId);
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            writeTextFileAtomically(join(dir, "start.json"), `${JSON.stringify(marker, null, 2)}\n`);
+        },
+        readStartMarker(taskId, jobId) {
+            return readJsonFile(join(home, "artifacts", "jobs", taskId, jobId, "start.json"));
+        },
+        readReadyFile(taskId, jobId) {
+            return readJsonFile(join(home, "artifacts", "jobs", taskId, jobId, "ready.json"));
+        }
+    };
+}
+function readJsonFile(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/controller/providerHookRunFence.js

@@ -1,6 +1,7 @@
 import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
 import { hasRuntimeCleanupObligation, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
+import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactTaskRuntimeEnvironment, exactControlPlaneDigest, parseExactControlPlaneDescriptor, refreshReusedTaskRuntimeDescriptorSource } from "../runtime/exactControlPlane.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
 /**
  * Resolves turn identity from the current durable in-flight fence. The one
@@ -21,9 +22,13 @@ export function resolveProviderHookRunFence(environment, adapterId, payloadNativ
     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 runtimeSource = environment[YUI_TASK_RUNTIME_DESCRIPTOR];
+    const runtime = runtimeSource === undefined
+        ? undefined
+        : assertExactTaskRuntimeEnvironment(runtimeSource, environment, exactControlPlaneDigest(parseExactControlPlaneDescriptor(requireIdentity(environment[YUI_CONTROL_PLANE_DESCRIPTOR], "Exact control-plane descriptor"))), home);
+    const launchId = requireIdentity(runtime?.launchId ?? environment.YUI_LAUNCH_ID, "Launch id");
     const nativeSessionId = requireIdentity(payloadNativeSessionId, "Provider session id");
-    const expectedNativeSessionId = environment.YUI_NATIVE_SESSION_ID;
+    const expectedNativeSessionId = runtime?.nativeSessionId ?? 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.");
@@ -52,7 +57,7 @@ export function resolveProviderHookRunFence(environment, adapterId, payloadNativ
         && !hasRuntimeCleanupObligation(mailbox);
     const executionRef = mailbox?.processing?.executionRef;
     const startupRunId = options.allowPreallocatedClaudeStartup === true
-        ? requireIdentity(environment.YUI_RUN_ID, "Run id")
+        ? requireIdentity(runtime?.runId ?? environment.YUI_RUN_ID, "Run id")
         : undefined;
     const deterministicClaudeStartup = adapterId === "claude"
         && options.allowPreallocatedClaudeStartup === true
@@ -77,6 +82,30 @@ export function resolveProviderHookRunFence(environment, adapterId, payloadNativ
         throw new Error("Provider lifecycle hook has no matching durable in-flight Run.");
     }
     const runId = inFlight?.runId ?? startupRunId;
+    let effectiveRuntime = runtime;
+    let effectiveLaunchId = launchId;
+    const sessionLaunchId = session?.launchId;
+    if (runtime !== undefined
+        && session !== undefined
+        && sessionLaunchId !== undefined
+        && typeof runtimeSource === "string"
+        && !runtimeSource.trimStart().startsWith("{")
+        && (runtime.runId !== runId
+            || runtime.launchId !== sessionLaunchId
+            || runtime.nativeSessionId !== session.nativeSessionId)) {
+        // A reused native pane keeps its original descriptor source. Advance only
+        // that Hook-owned source to the current durable generation before the
+        // volatile fence; the Controller no longer scans history to keep it fresh.
+        effectiveRuntime = refreshReusedTaskRuntimeDescriptorSource(runtimeSource, home, store, {
+            runId,
+            launchId: sessionLaunchId,
+            nativeSessionId: session.nativeSessionId
+        });
+        effectiveLaunchId = effectiveRuntime.launchId;
+    }
+    if (effectiveRuntime?.runId !== undefined && effectiveRuntime.runId !== runId) {
+        throw new Error("Provider lifecycle hook Run does not match its current descriptor.");
+    }
     const run = store.getActiveAgentRun(taskId, roleName);
     if (run === null
         || run.id !== runId
@@ -90,7 +119,7 @@ export function resolveProviderHookRunFence(environment, adapterId, payloadNativ
     }
     if (session !== undefined) {
         if (session.adapterId !== adapterId
-            || session.launchId !== launchId
+            || session.launchId !== effectiveLaunchId
             || session.nativeSessionId !== nativeSessionId
             || session.effective.workspace.root !== workspace) {
             throw new Error("Provider lifecycle hook Session does not match its durable generation.");
@@ -108,7 +137,7 @@ export function resolveProviderHookRunFence(environment, adapterId, payloadNativ
         taskId,
         roleName,
         agentId,
-        launchId,
+        launchId: effectiveLaunchId,
         runId,
         ...(inFlight?.receiptId === undefined ? {} : { receiptId: inFlight.receiptId }),
         nativeSessionId,

package/dist/controller/resourceCleanupLinux.js

@@ -1,8 +1,8 @@
 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 { tmuxSocketDirectory, tmuxSocketEnvironment } from "../tmux/tmuxSocketEndpoint.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;
@@ -17,7 +17,7 @@ export async function cleanControllerResource(resource, options = {}) {
     const ports = options.ports ?? linuxCleanupPorts(environment);
     const cleanup = async () => {
         if (resource.artifact !== undefined) {
-            cleanArtifact(resource, ports);
+            cleanArtifact(resource, ports, environment);
             return;
         }
         if (resource.kind === "agent-session") {
@@ -88,11 +88,11 @@ function assertEphemeralDomainFence(resource) {
         throw new Error(`Resource changed since scan: ${resource.id}.`);
     }
 }
-function cleanArtifact(resource, ports) {
+function cleanArtifact(resource, ports, environment) {
     const artifact = resource.artifact;
     if (artifact === undefined)
         throw new Error(`Artifact is unavailable: ${resource.id}.`);
-    assertOwnedArtifactPath(resource);
+    assertOwnedArtifactPath(resource, environment);
     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.
@@ -205,7 +205,18 @@ function tmuxManagerForResource(resource, environment) {
     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 });
+    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 });
 }
 function readProcessStartIdentity(pid) {
     try {
@@ -232,15 +243,13 @@ function unixSocketIsActive(expectedPath) {
         return true;
     }
 }
-function assertOwnedArtifactPath(resource) {
+function assertOwnedArtifactPath(resource, environment) {
     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
+        if (dirname(path) !== tmuxSocketDirectory(environment)
             || !/^yui-[a-f0-9]{24}$/u.test(basename(path))) {
             throw new Error(`Artifact path is outside the Yui tmux namespace: ${path}.`);
         }