@zq-silk/yui 0.6.5 → 0.6.7

package/dist/controller/runtimeEventProcessor.js

@@ -6,6 +6,7 @@ export class FileRuntimeEventProcessor {
     observer;
     options;
     drivers;
+    drainLaneCursor = 0;
     constructor(inbox, observer, options = {}) {
         this.inbox = inbox;
         this.observer = observer;
@@ -25,39 +26,62 @@ export class FileRuntimeEventProcessor {
         }
         const coalesced = coalesceRuntimeProgress(events);
         const maximum = positiveInteger(this.options.maxEventsPerDrain, DEFAULT_MAX_RUNTIME_EVENTS_PER_DRAIN);
-        const selected = selectDrainBatch(coalesced, maximum);
+        const selection = selectDrainBatch(coalesced, maximum, this.drainLaneCursor);
+        this.drainLaneCursor = selection.nextLaneCursor;
+        const selected = selection.candidates;
+        const failedTaskIds = new Set();
         let stateTransactions = 0;
         if (selected.length > 0 && this.observer.withRuntimeEventTransaction !== undefined) {
-            try {
-                stateTransactions += 1;
-                const folded = this.observer.withRuntimeEventTransaction(() => (selected.map((candidate) => this.foldOne(candidate, now))));
-                for (const result of folded) {
-                    this.finalizeOne(result, acknowledgedEventIds, deferred, failed);
-                }
-            }
-            catch {
-                // A failed aggregate transaction commits nothing. Retry each candidate
-                // independently so one bad event cannot strand unrelated facts.
-                for (const candidate of selected) {
-                    try {
-                        stateTransactions += 1;
-                        const folded = this.observer.withRuntimeEventTransaction(() => (this.foldOne(candidate, now)));
-                        this.finalizeOne(folded, acknowledgedEventIds, deferred, failed);
+            let offset = 0;
+            while (offset < selected.length) {
+                const wave = selectTaskOrderedWave(selected, offset, failedTaskIds);
+                offset = wave.nextOffset;
+                if (wave.candidates.length === 0)
+                    continue;
+                try {
+                    stateTransactions += 1;
+                    const folded = this.observer.withRuntimeEventTransaction(() => (wave.candidates.map((candidate) => this.foldOne(candidate, now))));
+                    for (const result of folded) {
+                        const failure = this.finalizeOne(result, acknowledgedEventIds, deferred);
+                        if (failure !== undefined) {
+                            recordDrainFailure(failure, failed, failedTaskIds);
+                        }
                     }
-                    catch (candidateError) {
-                        failed.push({ eventId: candidate.event.id, error: candidateError });
+                }
+                catch {
+                    // A failed aggregate transaction commits nothing. Retry each candidate
+                    // independently so one bad event cannot strand unrelated Tasks.
+                    for (const candidate of wave.candidates) {
+                        if (isTaskCandidateBlocked(candidate.event, failedTaskIds))
+                            continue;
+                        try {
+                            stateTransactions += 1;
+                            const folded = this.observer.withRuntimeEventTransaction(() => (this.foldOne(candidate, now)));
+                            const failure = this.finalizeOne(folded, acknowledgedEventIds, deferred);
+                            if (failure !== undefined) {
+                                recordDrainFailure(failure, failed, failedTaskIds);
+                            }
+                        }
+                        catch (candidateError) {
+                            recordDrainFailure(candidateDrainFailure(candidate.event, candidateError), failed, failedTaskIds);
+                        }
                     }
                 }
             }
         }
         else {
             for (const candidate of selected) {
+                if (isTaskCandidateBlocked(candidate.event, failedTaskIds))
+                    continue;
                 try {
                     const folded = this.foldOne(candidate, now);
-                    this.finalizeOne(folded, acknowledgedEventIds, deferred, failed);
+                    const failure = this.finalizeOne(folded, acknowledgedEventIds, deferred);
+                    if (failure !== undefined) {
+                        recordDrainFailure(failure, failed, failedTaskIds);
+                    }
                 }
                 catch (error) {
-                    failed.push({ eventId: candidate.event.id, error });
+                    recordDrainFailure(candidateDrainFailure(candidate.event, error), failed, failedTaskIds);
                 }
             }
         }
@@ -117,13 +141,13 @@ export class FileRuntimeEventProcessor {
         }
         return this.observer.observeRuntimeObservation?.(event.observation, now) ?? "obsolete";
     }
-    finalizeOne(folded, acknowledged, deferred, failed) {
+    finalizeOne(folded, acknowledged, deferred) {
         const { candidate, outcome } = folded;
         try {
             if (outcome === "deferred") {
                 deferred.push(candidate.event);
                 this.acknowledge(candidate.representedEventIds.filter((id) => id !== candidate.event.id), acknowledged);
-                return;
+                return undefined;
             }
             if (folded.notifyTaskRuntime) {
                 const event = candidate.event;
@@ -158,9 +182,10 @@ export class FileRuntimeEventProcessor {
                 }
             }
             this.acknowledge(candidate.representedEventIds, acknowledged);
+            return undefined;
         }
         catch (error) {
-            failed.push({ eventId: candidate.event.id, error });
+            return candidateDrainFailure(candidate.event, error);
         }
     }
     /**
@@ -331,11 +356,62 @@ export function coalesceRuntimeProgress(events, instrumentation = {}) {
     flush();
     return result;
 }
-function selectDrainBatch(events, maximum) {
-    // A batch is always an arrival-order prefix. Drain-time coalescing bounds
-    // worker folds without allowing a later semantic fact to
-    // overtake an earlier progress fence from another Run.
-    return events.slice(0, maximum);
+function selectDrainBatch(events, maximum, laneCursor = 0) {
+    // Select one candidate per Task per round. A poison prefix from one Task
+    // therefore cannot consume the whole bounded batch before a later Task gets
+    // a chance to fold. Each lane itself remains in arrival order, preserving
+    // the same-Task semantic fence; only cross-Task order is interleaved.
+    const lanes = new Map();
+    for (const candidate of events) {
+        const key = drainLaneKey(candidate.event);
+        const lane = lanes.get(key);
+        if (lane === undefined)
+            lanes.set(key, [candidate]);
+        else
+            lane.push(candidate);
+    }
+    const laneStates = [...lanes.values()].map((candidates) => ({
+        candidates,
+        offset: 0
+    }));
+    if (laneStates.length === 0) {
+        return { candidates: [], nextLaneCursor: 0 };
+    }
+    const startLane = positiveModulo(laneCursor, laneStates.length);
+    const selected = [];
+    let lastLane = startLane;
+    while (selected.length < maximum) {
+        let progressed = false;
+        for (let laneOffset = 0; laneOffset < laneStates.length; laneOffset += 1) {
+            const laneIndex = (startLane + laneOffset) % laneStates.length;
+            const lane = laneStates[laneIndex];
+            const candidate = lane.candidates[lane.offset];
+            if (candidate === undefined)
+                continue;
+            lane.offset += 1;
+            selected.push(candidate);
+            lastLane = laneIndex;
+            progressed = true;
+            if (selected.length >= maximum)
+                break;
+        }
+        // Every non-empty lane advances its offset when selected. Keep this
+        // guard explicit so malformed/empty input cannot create a zero-progress
+        // drain loop.
+        if (!progressed)
+            break;
+    }
+    return {
+        candidates: selected,
+        nextLaneCursor: (lastLane + 1) % laneStates.length
+    };
+}
+function positiveModulo(value, modulus) {
+    return ((value % modulus) + modulus) % modulus;
+}
+function drainLaneKey(event) {
+    const taskId = candidateTaskId(event);
+    return taskId === undefined ? "global" : `task:${taskId}`;
 }
 function progressStreamKey(event) {
     const { fence, payload } = event.observation;
@@ -362,7 +438,7 @@ function emptyDrainFailure(error) {
     return {
         acknowledgedEventIds: [],
         deferred: [],
-        failed: [{ error }],
+        failed: [{ scope: "unknown", error }],
         remainingEventCount: 0,
         metrics: {
             listedEventCount: 0,
@@ -388,6 +464,64 @@ function isObsoleteRuntimeTurnObservation(value) {
         && value !== null
         && value.disposition === "obsolete";
 }
+function candidateDrainFailure(event, error) {
+    const eventId = nonEmptyString(event.id);
+    if (event.scope === "task") {
+        const taskId = nonEmptyString(event.taskId);
+        if (eventId === undefined || taskId === undefined) {
+            // A Task failure must carry a durable inbox fence. If an injected port
+            // violates that parsed-event contract, do not incorrectly isolate it.
+            return {
+                ...(eventId === undefined ? {} : { eventId }),
+                scope: "unknown",
+                error
+            };
+        }
+        return { eventId, scope: "task", taskId, error };
+    }
+    return {
+        ...(eventId === undefined ? {} : { eventId }),
+        scope: "global",
+        error
+    };
+}
+function selectTaskOrderedWave(candidates, offset, failedTaskIds) {
+    const selected = [];
+    const selectedTaskIds = new Set();
+    let nextOffset = offset;
+    while (nextOffset < candidates.length) {
+        const candidate = candidates[nextOffset];
+        const taskId = candidateTaskId(candidate.event);
+        if (taskId !== undefined && failedTaskIds.has(taskId)) {
+            nextOffset += 1;
+            continue;
+        }
+        if (taskId !== undefined && selectedTaskIds.has(taskId))
+            break;
+        selected.push(candidate);
+        if (taskId !== undefined)
+            selectedTaskIds.add(taskId);
+        nextOffset += 1;
+    }
+    return { candidates: selected, nextOffset };
+}
+function recordDrainFailure(failure, failed, failedTaskIds) {
+    failed.push(failure);
+    if (failure.scope === "task")
+        failedTaskIds.add(failure.taskId);
+}
+function isTaskCandidateBlocked(event, failedTaskIds) {
+    const taskId = candidateTaskId(event);
+    return taskId !== undefined && failedTaskIds.has(taskId);
+}
+function candidateTaskId(event) {
+    if (event.scope !== "task" || nonEmptyString(event.id) === undefined)
+        return undefined;
+    return nonEmptyString(event.taskId);
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
 /**
  * Build an {@link AsyncRuntimeTurnEventObserver} that forwards every fold to the
  * worker-hosted adapter via {@link AsyncObserverInvoker}. The adapter's fold
@@ -416,6 +550,7 @@ export class AsyncRuntimeEventProcessor {
     observer;
     options;
     drivers;
+    drainLaneCursor = 0;
     constructor(inbox, observer, options = {}) {
         this.inbox = inbox;
         this.observer = observer;
@@ -435,9 +570,14 @@ export class AsyncRuntimeEventProcessor {
         }
         const coalesced = coalesceRuntimeProgress(events);
         const maximum = positiveInteger(this.options.maxEventsPerDrain, DEFAULT_MAX_RUNTIME_EVENTS_PER_DRAIN);
-        const selected = selectDrainBatch(coalesced, maximum);
+        const selection = selectDrainBatch(coalesced, maximum, this.drainLaneCursor);
+        this.drainLaneCursor = selection.nextLaneCursor;
+        const selected = selection.candidates;
+        const failedTaskIds = new Set();
         for (const candidate of selected) {
             const event = candidate.event;
+            if (isTaskCandidateBlocked(event, failedTaskIds))
+                continue;
             try {
                 let outcome = "applied";
                 if (event.type === "native-turn-completed") {
@@ -460,7 +600,7 @@ export class AsyncRuntimeEventProcessor {
                 this.acknowledge(candidate.representedEventIds, acknowledgedEventIds);
             }
             catch (error) {
-                failed.push({ eventId: event.id, error });
+                recordDrainFailure(candidateDrainFailure(event, error), failed, failedTaskIds);
             }
         }
         const acknowledged = new Set(acknowledgedEventIds);

package/dist/controller/updateReconciliation.js

@@ -0,0 +1,113 @@
+import { resolve } from "node:path";
+import { acquireHomeLifecycleLock } from "../core/controllerServer.js";
+import { cleanControllerResource } from "./resourceCleanupLinux.js";
+import { scanControllerResourceInventory } from "./resourceInventoryLinux.js";
+const MAX_RECONCILIATION_PASSES = 4;
+/**
+ * Reconcile only Controller-owned resources for the Home being updated.
+ *
+ * A current Controller is preserved for the update orchestrator's exact
+ * capture/stop handoff. Superseded/orphaned Controller processes and stale
+ * discovery/socket artifacts are cleaned using their existing process-start
+ * and inode fingerprints. Agent, tmux, app, and foreign-Home resources are
+ * deliberately outside this operation.
+ */
+export async function reconcileControllerResourcesForUpdate(home, environment = process.env) {
+    const resolvedHome = resolve(home);
+    const releaseLock = await acquireHomeLifecycleLock(resolvedHome, {
+        removeStaleOwner: true
+    });
+    const cleaned = new Set();
+    try {
+        for (let pass = 0; pass < MAX_RECONCILIATION_PASSES; pass += 1) {
+            const snapshot = await scanControllerResourceInventory({
+                currentHome: resolvedHome,
+                scope: "current",
+                environment
+            });
+            assertCertainSnapshot(snapshot, resolvedHome);
+            const resources = controllerResources(snapshot, resolvedHome);
+            const controllers = resources.filter(({ kind }) => kind === "controller");
+            const current = controllers.filter(({ state }) => state === "current");
+            if (current.length > 1) {
+                throw reconciliationBlocked(`multiple current Controllers were reported (${resourceLabels(current)})`);
+            }
+            const historical = controllers.filter(({ state }) => state !== "current");
+            const historicalCleanup = historical.filter(isCleanupEligible);
+            const unsafeHistorical = historical.filter((resource) => !isCleanupEligible(resource));
+            if (unsafeHistorical.length > 0) {
+                throw reconciliationBlocked(`historical Controller ownership is not safely cleanable (${resourceLabels(unsafeHistorical)})`);
+            }
+            const artifacts = resources.filter(isControllerArtifact);
+            const staleArtifactCleanup = artifacts.filter((resource) => (resource.state === "stale" && isCleanupEligible(resource)));
+            const unresolvedArtifacts = artifacts.filter((resource) => (!staleArtifactCleanup.includes(resource)));
+            // A corrupt discovery is conservatively marked active while an orphan
+            // Controller still exists. Remove the exactly fenced historical process
+            // first; the next scan can then reclassify and remove the stale artifact.
+            if (unresolvedArtifacts.length > 0 && historicalCleanup.length === 0) {
+                throw reconciliationBlocked(`a Controller artifact is active or ownership is unknown (${resourceLabels(unresolvedArtifacts)})`);
+            }
+            const candidates = [...historicalCleanup, ...staleArtifactCleanup];
+            if (candidates.length === 0) {
+                return { cleaned: [...cleaned] };
+            }
+            for (const candidate of candidates) {
+                try {
+                    await cleanControllerResource(candidate, { environment });
+                    cleaned.add(candidate.id);
+                }
+                catch (error) {
+                    // A concurrent exact cleanup that already reached the desired state
+                    // is harmless. Anything still present or reclassified is a real
+                    // ownership change and must remain a user-visible blocker.
+                    const afterFailure = await scanControllerResourceInventory({
+                        currentHome: resolvedHome,
+                        scope: "current",
+                        environment
+                    });
+                    assertCertainSnapshot(afterFailure, resolvedHome);
+                    if (!controllerResources(afterFailure, resolvedHome).some(({ id }) => id === candidate.id)) {
+                        cleaned.add(candidate.id);
+                        continue;
+                    }
+                    throw reconciliationBlocked(`resource ${candidate.id} changed or could not be cleaned: ${messageOf(error)}`);
+                }
+            }
+        }
+        throw reconciliationBlocked("Controller resources did not converge after bounded cleanup");
+    }
+    finally {
+        await releaseLock();
+    }
+}
+function assertCertainSnapshot(snapshot, resolvedHome) {
+    if (snapshot.scope !== "current"
+        || resolve(snapshot.currentHome) !== resolvedHome) {
+        throw reconciliationBlocked("the Controller inventory returned a mismatched Home or scope");
+    }
+    if (snapshot.warnings.length > 0) {
+        throw reconciliationBlocked(`the Controller inventory is uncertain: ${snapshot.warnings.join("; ")}`);
+    }
+}
+function controllerResources(snapshot, resolvedHome) {
+    return snapshot.resources.filter((resource) => (resource.yuiHome === resolvedHome
+        && (resource.kind === "controller" || isControllerArtifact(resource))));
+}
+function isControllerArtifact(resource) {
+    return resource.kind === "artifact"
+        && (resource.artifact?.artifactKind === "controller-discovery"
+            || resource.artifact?.artifactKind === "controller-socket");
+}
+function isCleanupEligible(resource) {
+    return resource.disposition === "safe" || resource.disposition === "review";
+}
+function resourceLabels(resources) {
+    return resources.map((resource) => `${resource.id}:${resource.reasonCode}`).join(", ");
+}
+function reconciliationBlocked(reason) {
+    return new Error(`Automatic Controller reconciliation is blocked because ${reason}. `
+        + "Run `yui controller status --verbose` and resolve only the reported current-Home resource before retrying.");
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/coordination/keyedWorkQueue.js

@@ -0,0 +1,189 @@
+/**
+ * A FIFO work queue that coalesces signals by key.
+ *
+ * At most one item for a key can be processing. Signals received while that
+ * key is processing mark it dirty, causing exactly one replay at the FIFO tail
+ * after the current item is done. Different keys can be leased concurrently by
+ * multiple consumers.
+ *
+ * shutdown() is graceful: it stops accepting signals but preserves all work
+ * accepted before shutdown, including dirty replays. abortPending() instead
+ * drops queued work and dirty replays while allowing leased items to finish.
+ * Consumers must complete every leased item. drain() only waits for an idle
+ * queue; it does not close the queue or process work itself.
+ */
+export class KeyedWorkQueue {
+    #states = new Map();
+    #ready = [];
+    #takeWaiters = [];
+    #drainWaiters = [];
+    #readyHead = 0;
+    #takeWaiterHead = 0;
+    #closed = false;
+    #aborted = false;
+    #closeCompletion;
+    /**
+     * Adds or coalesces a key. Returns false after either stop mode has started.
+     */
+    signal(key) {
+        if (this.#closed)
+            return false;
+        const state = this.#states.get(key);
+        if (state === undefined) {
+            this.#states.set(key, { phase: "queued" });
+            this.#ready.push(key);
+            this.#dispatchReadyWork();
+            return true;
+        }
+        if (state.phase === "processing")
+            state.dirty = true;
+        return true;
+    }
+    /**
+     * Leases the next ready key. It returns undefined after graceful shutdown
+     * has drained, or immediately after pending work has been aborted.
+     */
+    take() {
+        if (this.#aborted)
+            return Promise.resolve(undefined);
+        if (this.#hasReadyWork()) {
+            return Promise.resolve(this.#leaseReadyWork());
+        }
+        if (this.#closed && this.#states.size === 0) {
+            return Promise.resolve(undefined);
+        }
+        return new Promise((resolve) => {
+            this.#takeWaiters.push(resolve);
+        });
+    }
+    /**
+     * Resolves the next time no key is queued or processing. Later signals may
+     * make the queue non-idle again unless shutdown() has already started.
+     */
+    drain() {
+        if (this.#states.size === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            this.#drainWaiters.push(resolve);
+        });
+    }
+    /**
+     * Stops accepting signals and resolves after all previously accepted work
+     * has been completed. Calling shutdown repeatedly returns the same promise.
+     */
+    shutdown() {
+        const stopped = this.#beginClose();
+        this.#settleIdleWaiters();
+        return stopped;
+    }
+    /**
+     * Stops accepting signals, drops queued keys and dirty replays, and resolves
+     * after already leased items are completed. Pending and later take() calls
+     * receive undefined. Repeated calls are idempotent.
+     */
+    abortPending() {
+        const stopped = this.#beginClose();
+        if (this.#aborted)
+            return stopped;
+        this.#aborted = true;
+        for (const [key, state] of this.#states) {
+            if (state.phase === "queued") {
+                this.#states.delete(key);
+            }
+            else {
+                state.dirty = false;
+            }
+        }
+        this.#ready.length = 0;
+        this.#readyHead = 0;
+        this.#resolveTakeWaiters();
+        this.#settleIdleWaiters();
+        return stopped;
+    }
+    #hasReadyWork() {
+        return this.#readyHead < this.#ready.length;
+    }
+    #hasTakeWaiter() {
+        return this.#takeWaiterHead < this.#takeWaiters.length;
+    }
+    #leaseReadyWork() {
+        const key = this.#ready[this.#readyHead++];
+        if (!this.#hasReadyWork()) {
+            this.#ready.length = 0;
+            this.#readyHead = 0;
+        }
+        const state = this.#states.get(key);
+        if (state?.phase !== "queued") {
+            throw new Error("Keyed work queue invariant failed: ready key was not queued.");
+        }
+        const token = Symbol("keyed-work-item");
+        this.#states.set(key, { phase: "processing", dirty: false, token });
+        let completed = false;
+        return {
+            key,
+            done: () => {
+                if (completed)
+                    throw new Error("Keyed work item was already completed.");
+                completed = true;
+                this.#complete(key, token);
+            }
+        };
+    }
+    #complete(key, token) {
+        const state = this.#states.get(key);
+        if (state?.phase !== "processing" || state.token !== token) {
+            throw new Error("Keyed work queue invariant failed: completed lease is not active.");
+        }
+        if (state.dirty && !this.#aborted) {
+            this.#states.set(key, { phase: "queued" });
+            this.#ready.push(key);
+            this.#dispatchReadyWork();
+            return;
+        }
+        this.#states.delete(key);
+        this.#settleIdleWaiters();
+    }
+    #dispatchReadyWork() {
+        while (this.#hasReadyWork() && this.#hasTakeWaiter()) {
+            const resolve = this.#takeWaiters[this.#takeWaiterHead++];
+            const item = this.#leaseReadyWork();
+            resolve(item);
+        }
+        if (!this.#hasTakeWaiter()) {
+            this.#takeWaiters.length = 0;
+            this.#takeWaiterHead = 0;
+        }
+    }
+    #settleIdleWaiters() {
+        if (this.#states.size !== 0)
+            return;
+        const drains = this.#drainWaiters.splice(0);
+        for (const resolve of drains)
+            resolve();
+        if (!this.#closed)
+            return;
+        this.#resolveTakeWaiters();
+        this.#closeCompletion?.resolve();
+    }
+    #beginClose() {
+        if (this.#closeCompletion === undefined) {
+            this.#closeCompletion = completion();
+            this.#closed = true;
+        }
+        return this.#closeCompletion.promise;
+    }
+    #resolveTakeWaiters() {
+        while (this.#hasTakeWaiter()) {
+            this.#takeWaiters[this.#takeWaiterHead++](undefined);
+        }
+        this.#takeWaiters.length = 0;
+        this.#takeWaiterHead = 0;
+    }
+}
+function completion() {
+    let resolve;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}

package/dist/core/controllerServer.js

@@ -763,7 +763,7 @@ function safeErrorMessage(message) {
         .slice(0, 512);
     return safe.length === 0 ? undefined : safe;
 }
-async function acquireHomeLifecycleLock(home) {
+export async function acquireHomeLifecycleLock(home, options = {}) {
     const lockPath = homeLifecycleLockPath(home);
     await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
     const owner = Object.freeze({
@@ -796,6 +796,12 @@ async function acquireHomeLifecycleLock(home) {
         if (isProcessAlive(existing.pid)) {
             throw new Error(`Another Yui home lifecycle operation is already running (${ownerDescription}): ${lockPath}`);
         }
+        if (options.removeStaleOwner === true) {
+            // The token comparison in releaseHomeLifecycleLock is the CAS fence: a
+            // replacement owner that appeared after the read is never removed.
+            await releaseHomeLifecycleLock(lockPath, existing);
+            continue;
+        }
         throw new Error(`A previous Yui home lifecycle operation left a stale lock `
             + `(${ownerDescription}): ${lockPath}. `
             + "If no Controller startup or development reset is running, "

package/dist/runtime/runtimeSessionCandidate.js

@@ -0,0 +1,43 @@
+import { activeRoleAgentSession } from "../executor/agentExecutor.js";
+/** Exact completed-Task cleanup contract shared by projection writers/readers. */
+export function runtimeSessionRequiresCleanup(input) {
+    if (input.status === "stopped" || input.status === "broken")
+        return false;
+    return input.status === "running" || input.launchId !== undefined;
+}
+/** Projects only the current active Agent Session; stopped history disappears. */
+export function projectRuntimeSessionCandidate(sessions) {
+    const active = activeRoleAgentSession(sessions);
+    if (active === null || active.status === "stopped")
+        return null;
+    return {
+        owner: sessions.owner.scope === "task"
+            ? {
+                scope: "task",
+                taskId: sessions.owner.taskId,
+                roleName: sessions.owner.roleName
+            }
+            : { scope: "global", roleName: sessions.owner.roleName },
+        agentId: active.agentId,
+        adapterId: active.adapterId,
+        nativeSessionId: active.nativeSessionId,
+        ...(active.launchId === undefined ? {} : { launchId: active.launchId }),
+        status: active.status,
+        sessionUpdatedAt: active.updatedAt,
+        cleanupRequired: runtimeSessionRequiresCleanup(active)
+    };
+}
+/** Deterministic owner order shared by all storage backends. */
+export function compareRuntimeSessionCandidates(left, right) {
+    if (left.owner.scope !== right.owner.scope) {
+        // Preserve the historical adapter contract: Task owners precede the
+        // bounded global Role set.
+        return left.owner.scope === "task" ? -1 : 1;
+    }
+    if (left.owner.scope === "task" && right.owner.scope === "task") {
+        const task = left.owner.taskId.localeCompare(right.owner.taskId, undefined, { numeric: true });
+        if (task !== 0)
+            return task;
+    }
+    return left.owner.roleName.localeCompare(right.owner.roleName, undefined, { numeric: true });
+}

package/dist/scheduler/activeRoleRunDelivery.js

@@ -1,4 +1,4 @@
-import { selectedSchedulerRoles, selectedSchedulerTasks } from "./ports.js";
+import { selectedSchedulerRoles, selectedActiveSchedulerTasks } from "./ports.js";
 import { isSchedulerTaskWorkspaceReady } from "./ports.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
 import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain } from "../executor/effectiveLaunch.js";
@@ -11,9 +11,7 @@ import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
  */
 export async function processActiveRoleRunDeliveries(store, delivery, now, selection) {
     const results = [];
-    for (const task of selectedSchedulerTasks(store, selection)) {
-        if (task.status !== "active")
-            continue;
+    for (const task of selectedActiveSchedulerTasks(store, selection)) {
         for (const role of selectedSchedulerRoles(store, task.id, selection)) {
             const run = store.getActiveAgentRun(task.id, role.name);
             // A crash after a Leader wake is durably claimed but before tmux input