@zq-silk/yui 0.15.7 → 0.15.9

package/dist/controller/structuredProviderObservation.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { callController } from "../core/controllerClient.js";
+import { callController, ControllerClientError } from "../core/controllerClient.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { standardAgentError } from "../runtime/agentError.js";
 import { transportAgentResult } from "../domain/agentResultTransport.js";
@@ -7,15 +7,75 @@ import { createRuntimeObservation, runtimeObservationSemanticKey } from "../runt
 import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
 import { isForeignHandoverLockHeld } from "../release/runtimeRelease.js";
 import { FileRuntimeEventInbox } from "./runtimeEventInbox.js";
-import { resolveRuntimeHookTurnFence } from "./runtimeHookTurnFence.js";
-import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
+import { resolveRuntimeHookRunFence } from "./runtimeHookRunFence.js";
 let structuredSequence = 0;
+export async function publishStructuredProviderAttachmentExit(input) {
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
+    const owner = resolveRuntimeHookRunFence(input.environment, adapterId, input.nativeSessionId, {
+        terminal: true, attemptId: input.attemptId, nativeTurnId: input.nativeTurnId
+    });
+    await persistAndApply(input.home, [observation({
+            kind: input.failed ? "session.failed" : "session.ended", observedAt: input.observedAt,
+            sequence: nextStructuredSequence(), ordinal: 0,
+            fence: {
+                taskId: owner.taskId, roleName: owner.roleName, agentId: owner.agentId, driverId: driver.id,
+                nativeSessionId: input.nativeSessionId, conversationId: input.nativeSessionId,
+                ...(owner.runId === undefined ? {} : { runId: owner.runId }),
+                ...(input.attemptId === undefined ? {} : { receiptId: input.attemptId }),
+                ...(input.nativeTurnId === undefined ? {} : { nativeTurnId: input.nativeTurnId })
+            }
+        })], owner.taskId, owner.roleName);
+}
+export async function publishStructuredProviderActivity(input) {
+    const activity = input.activity;
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
+    const owner = resolveRuntimeHookRunFence(input.environment, adapterId, activity.nativeSessionId, {
+        nativeTurnId: activity.nativeTurnId, attemptId: activity.attemptId
+    });
+    const event = observation({
+        kind: activity.phase === "model" ? "activity.observed" : `operation.${activity.phase}`,
+        observedAt: activity.observedAt, sequence: nextStructuredSequence(), ordinal: 0,
+        fence: {
+            taskId: owner.taskId, roleName: owner.roleName,
+            ...(owner.runId === undefined ? {} : { runId: owner.runId }),
+            agentId: owner.agentId, driverId: driver.id,
+            nativeSessionId: activity.nativeSessionId, conversationId: activity.conversationId,
+            receiptId: activity.attemptId,
+            ...(activity.nativeTurnId === undefined ? {} : { nativeTurnId: activity.nativeTurnId })
+        },
+        payload: activity.phase === "model"
+            ? { activity: "model", activityId: activity.id }
+            : { operation: "tool", operationId: activity.id }
+    });
+    await persistAndApply(input.home, [event], owner.taskId, owner.roleName);
+}
+/** An exact provider item id is evidence of visible input, not an inferred
+ * human author. The original managed request is never replaced.
+ */
+export async function publishStructuredProviderInputObserved(input) {
+    const observed = input.observed;
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, observed.nativeSessionId, {
+        nativeTurnId: observed.nativeTurnId, terminal: true, sessionOnly: true
+    });
+    if (fence.runId === undefined)
+        return; // Ordinary chat need not be mirrored.
+    await persistAndApply(input.home, [observation({
+            kind: "input.accepted", observedAt: observed.observedAt, sequence: nextStructuredSequence(), ordinal: 0,
+            fence: { ...fence, driverId: builtinAgentDriverRegistry().requireByAdapterId(adapterId).id,
+                conversationId: observed.conversationId, nativeTurnId: observed.nativeTurnId,
+                receiptId: `native-input:${observed.nativeTurnId}/${observed.inputId}` },
+            payload: { input: observed.input }
+        })], fence.taskId, fence.roleName);
+}
 export async function publishStructuredProviderStarted(input) {
     if (input.started.clientOwned)
         return;
     const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
     const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
-    const fence = resolveRuntimeHookTurnFence(input.environment, adapterId, input.started.nativeSessionId, {
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.started.nativeSessionId, {
         nativeTurnId: input.started.nativeTurnId,
         sessionOnly: true
     });
@@ -30,9 +90,7 @@ export async function publishStructuredProviderStarted(input) {
             roleName: fence.roleName,
             agentId: fence.agentId,
             driverId: driver.id,
-            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.started.conversationId,
-            activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: input.started.nativeSessionId,
             nativeTurnId: input.started.nativeTurnId,
             receiptId
@@ -45,7 +103,7 @@ export async function publishStructuredProviderAccepted(input) {
     const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
     const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
     const startupSession = driver.capabilities.observation.sessionBootstrap;
-    const fence = resolveRuntimeHookTurnFence(input.environment, adapterId, input.receipt.nativeSessionId, {
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.receipt.nativeSessionId, {
         startupSession,
         nativeTurnId: input.receipt.nativeTurnId,
         attemptId: input.receipt.attemptId
@@ -54,23 +112,21 @@ export async function publishStructuredProviderAccepted(input) {
     const commonFence = {
         taskId: fence.taskId,
         roleName: fence.roleName,
-        ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
+        ...(fence.runId === undefined ? {} : { runId: fence.runId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.receipt.conversationId,
-        activationId: executionActivationId(input.home, fence, input.activationId, input.receipt.nativeSessionId),
         nativeSessionId: input.receipt.nativeSessionId,
         ...(input.receipt.nativeTurnId === undefined ? {} : {
             nativeTurnId: input.receipt.nativeTurnId
         }),
         // The structured Host owns the exact input attempt identity. Runtime
-        // descriptor receipts name the Turn bootstrap and must not overwrite a
-        // continuation or human-takeover Turn.
+        // descriptor receipts name the AgentRun bootstrap and must not overwrite a
+        // continuation or human-takeover AgentRun.
         receiptId: input.receipt.attemptId
     };
     const baseSequence = nextStructuredSequence();
-    // Opening owns the Session/Activation lifecycle. A receipt arriving after
+    // Opening owns the Session lifecycle. A receipt arriving after
     // its terminal must not reopen either lifecycle as an acceptance side effect.
     const observations = [observation({
             kind: "turn.accepted",
@@ -82,20 +138,62 @@ export async function publishStructuredProviderAccepted(input) {
         })];
     await persistAndApply(input.home, observations, fence.taskId, fence.roleName);
 }
+/** Steer settles an additional input, never the parent AgentRun's initial delivery. */
+export async function publishStructuredProviderInputSettlement(input) {
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.nativeSessionId, {
+        nativeTurnId: input.nativeTurnId,
+        terminal: true
+    });
+    if (fence.runId === undefined)
+        throw new Error("Steer settlement has no exact original AgentRun.");
+    const entry = observation({
+        kind: input.status === "accepted" ? "input.accepted"
+            : input.status === "rejected" ? "input.rejected" : "input.delivery-unknown",
+        observedAt: new Date().toISOString(),
+        sequence: nextStructuredSequence(),
+        ordinal: 0,
+        fence: {
+            taskId: fence.taskId,
+            roleName: fence.roleName,
+            runId: fence.runId,
+            agentId: fence.agentId,
+            driverId: driver.id,
+            conversationId: input.nativeSessionId,
+            nativeSessionId: input.nativeSessionId,
+            nativeTurnId: input.nativeTurnId,
+            receiptId: input.attemptId
+        },
+        payload: {
+            input: input.boundedText,
+            ...(input.failure === undefined ? {} : {
+                failure: {
+                    error: standardAgentError({
+                        source: "host",
+                        phase: "turn-submit",
+                        message: input.failure.detail,
+                        raw: input.failure.raw ?? input.failure.detail,
+                        inputDisposition: input.status === "unknown" ? "unknown" : "not-accepted"
+                    })
+                }
+            })
+        }
+    });
+    await persistAndApply(input.home, [entry], fence.taskId, fence.roleName);
+}
 export async function publishStructuredProviderOpened(input) {
     const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
     const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
     const startupSession = driver.capabilities.observation.sessionBootstrap;
-    const fence = resolveRuntimeHookTurnFence(input.environment, adapterId, input.nativeSessionId, { startupSession });
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.nativeSessionId, { startupSession });
     const commonFence = {
         taskId: fence.taskId,
         roleName: fence.roleName,
-        ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
+        ...(fence.runId === undefined ? {} : { runId: fence.runId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.conversationId,
-        activationId: requireIdentity(input.activationId, "Provider Activation id"),
         nativeSessionId: input.nativeSessionId,
         ...(fence.receiptId === undefined ? {} : { receiptId: fence.receiptId })
     };
@@ -113,19 +211,13 @@ export async function publishStructuredProviderOpened(input) {
             ordinal: 1,
             fence: commonFence,
             payload: { recoverability: input.recoverability }
-        }), observation({
-            kind: "activation.started",
-            observedAt: input.observedAt,
-            sequence,
-            ordinal: 2,
-            fence: commonFence
         })];
     await persistAndApply(input.home, observations, fence.taskId, fence.roleName);
 }
 export async function publishStructuredProviderGoal(input) {
     const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
     const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
-    const fence = resolveRuntimeHookTurnFence(input.environment, adapterId, input.conversationId, { sessionOnly: true });
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.conversationId, { sessionOnly: true });
     const goal = input.goal;
     const observedAt = input.observedAt ?? goal?.updatedAt ?? new Date().toISOString();
     const goalObservation = observation({
@@ -138,9 +230,7 @@ export async function publishStructuredProviderGoal(input) {
             roleName: fence.roleName,
             agentId: fence.agentId,
             driverId: driver.id,
-            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.conversationId,
-            activationId: requireIdentity(input.activationId, "Provider Activation id"),
             nativeSessionId: input.conversationId
         },
         payload: goal === null ? {} : {
@@ -156,27 +246,19 @@ export async function publishStructuredProviderGoal(input) {
 export async function publishStructuredConversationRecoverability(input) {
     const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
     const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
-    const fence = resolveRuntimeHookTurnFence(input.environment, adapterId, input.conversationId);
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.conversationId, { sessionOnly: true });
     const sequence = nextStructuredSequence();
     const observationFence = {
         taskId: fence.taskId,
         roleName: fence.roleName,
-        ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
+        ...(fence.runId === undefined ? {} : { runId: fence.runId }),
         agentId: fence.agentId,
         driverId: driver.id,
-        runtimeGenerationId: fence.runtimeGenerationId,
         conversationId: input.conversationId,
-        activationId: requireIdentity(input.activationId, "Provider Activation id"),
         nativeSessionId: input.conversationId,
         ...(fence.receiptId === undefined ? {} : { receiptId: fence.receiptId })
     };
     const observations = [observation({
-            kind: "activation.started",
-            observedAt: input.observedAt,
-            sequence,
-            ordinal: 0,
-            fence: observationFence
-        }), observation({
             kind: "conversation.observed",
             observedAt: input.observedAt,
             sequence,
@@ -184,22 +266,12 @@ export async function publishStructuredConversationRecoverability(input) {
             fence: observationFence,
             payload: { recoverability: input.recoverability }
         })];
-    if (input.recoverability === "unrecoverable") {
-        observations.push(observation({
-            kind: "activation.failed",
-            observedAt: input.observedAt,
-            sequence,
-            ordinal: 2,
-            fence: observationFence,
-            payload: {}
-        }));
-    }
     await persistAndApply(input.home, observations, fence.taskId, fence.roleName);
 }
 export async function publishStructuredProviderTerminal(input) {
     const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
     const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
-    const fence = resolveRuntimeHookTurnFence(input.environment, adapterId, input.terminal.nativeSessionId, {
+    const fence = resolveRuntimeHookRunFence(input.environment, adapterId, input.terminal.nativeSessionId, {
         terminal: true,
         nativeTurnId: input.terminal.nativeTurnId,
         attemptId: input.terminal.attemptId,
@@ -249,12 +321,10 @@ export async function publishStructuredProviderTerminal(input) {
         fence: {
             taskId: fence.taskId,
             roleName: fence.roleName,
-            ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
+            ...(fence.runId === undefined ? {} : { runId: fence.runId }),
             agentId: fence.agentId,
             driverId: driver.id,
-            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: input.terminal.conversationId,
-            activationId: executionActivationId(input.home, fence, input.activationId, input.terminal.nativeSessionId),
             nativeSessionId: input.terminal.nativeSessionId,
             ...(input.terminal.nativeTurnId === undefined ? {} : {
                 nativeTurnId: input.terminal.nativeTurnId
@@ -263,35 +333,15 @@ export async function publishStructuredProviderTerminal(input) {
                 ? fence.receiptId === undefined ? {} : { receiptId: fence.receiptId }
                 : { receiptId: input.terminal.attemptId })
         },
-        payload
+        payload: {
+            ...payload,
+            ...(kind !== "turn.completed" && transported.status === "completed"
+                ? { output: transported.output } : {}),
+            ...(input.terminal.input === undefined ? {} : { input: input.terminal.input })
+        }
     });
     await persistAndApply(input.home, [terminalObservation], fence.taskId, fence.roleName);
 }
-export async function publishStructuredProviderActivationTerminal(input) {
-    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
-    const driver = builtinAgentDriverRegistry().requireByAdapterId(adapterId);
-    const fence = resolveRuntimeHookTurnFence(input.environment, adapterId, input.nativeSessionId, { sessionOnly: true });
-    const terminal = observation({
-        kind: input.status === "failed" ? "activation.failed" : "activation.ended",
-        observedAt: input.observedAt,
-        sequence: nextStructuredSequence(),
-        ordinal: 0,
-        fence: {
-            taskId: fence.taskId,
-            roleName: fence.roleName,
-            ...(fence.turnId === undefined ? {} : { turnId: fence.turnId }),
-            agentId: fence.agentId,
-            driverId: driver.id,
-            runtimeGenerationId: fence.runtimeGenerationId,
-            conversationId: requireIdentity(input.conversationId, "Provider Conversation id"),
-            activationId: requireIdentity(input.activationId, "Provider Activation id"),
-            nativeSessionId: requireIdentity(input.nativeSessionId, "native Session id"),
-            ...(fence.receiptId === undefined ? {} : { receiptId: fence.receiptId })
-        },
-        payload: {}
-    });
-    await persistAndApply(input.home, [terminal], fence.taskId, fence.roleName);
-}
 function observation(input) {
     const eventId = `agent-host-${randomUUID()}`;
     const partial = {
@@ -330,24 +380,6 @@ function requireIdentity(value, label) {
     }
     return value.trim();
 }
-function executionActivationId(home, fence, sourceActivationId, nativeSessionId) {
-    const sourceId = requireIdentity(sourceActivationId, "Provider Activation id");
-    const store = openCurrentTaskStore(home);
-    try {
-        const binding = store.getTaskRoleSessionSet(fence.taskId, fence.roleName)?.providerBinding;
-        const source = binding?.activations.find(entry => entry.activationId === sourceId);
-        const original = binding?.activations.find(entry => entry.activationId === fence.runtimeGenerationId);
-        if (source?.conversationId !== nativeSessionId || original?.conversationId !== nativeSessionId) {
-            throw new Error("Structured execution observation source does not belong to its native Conversation.");
-        }
-        // A reattached collector can observe the old execution, but its current
-        // attachment must not replace that execution's durable Activation identity.
-        return original.activationId;
-    }
-    finally {
-        store.close();
-    }
-}
 async function persistAndApply(home, observations, taskId, roleName) {
     const inbox = new FileRuntimeEventInbox(home);
     for (const entry of observations)
@@ -362,17 +394,24 @@ async function persistAndApply(home, observations, taskId, roleName) {
         let result;
         try {
             result = await callController(home, "runtime.observation-apply", entry, {
-                timeoutMs: 10_000
+                // This is only an eager application hint after durable enqueue, not
+                // native admission. Bound it like the wake signal so a frozen
+                // Controller cannot serialize ten seconds of delay per tool event.
+                timeoutMs: 100
             });
         }
         catch (error) {
-            // Close the race where the handover begins after the first check but
-            // before this socket call. The durable entry remains pending for replay.
-            if (isForeignHandoverLockHeld(home))
+            // Persistence already succeeded. A stopped, frozen or reconnecting
+            // Controller only delays applying this exact observation; it does not
+            // fail the native execution or poison its reusable Host.
+            if (isForeignHandoverLockHeld(home)
+                || (error instanceof ControllerClientError
+                    && ["CONTROLLER_NOT_RUNNING", "CONTROLLER_UNAVAILABLE", "CONTROLLER_TIMEOUT",
+                        "CONTROLLER_DELIVERY_UNKNOWN"].includes(error.code)))
                 return;
             throw error;
         }
-        // A fast Provider can accept the initial Turn before the scheduler call
+        // A fast Provider can accept the initial AgentRun before the scheduler call
         // that launched this Host has returned and committed `turn.pushed`. The
         // immutable inbox entry already makes that exact fenced fact durable;
         // `deferred` therefore means "retained for replay", not delivery failure.

package/dist/coordination/workMailbox.js

@@ -315,7 +315,7 @@ function parseTarget(value) {
 function parseRef(value, label) {
     const ref = record(value, label);
     const types = [
-        "task", "turn", "work-item", "input", "session", "message", "event"
+        "task", "run", "work-item", "input", "session", "message", "event"
     ];
     if (!types.includes(ref.type))
         throw new Error(`${label} type is invalid`);
@@ -358,7 +358,7 @@ function copyTarget(target) {
             };
     }
 }
-function copyRef(ref) {
+export function copyRef(ref) {
     if (!("taskId" in ref)) {
         if (ref.type !== "task" && ref.type !== "session") {
             throw new Error(`entity reference taskId is required for ${ref.type}`);
@@ -373,7 +373,7 @@ function copyRef(ref) {
 }
 function mailboxTaskRecordKind(type) {
     switch (type) {
-        case "turn": return "turn";
+        case "run": return "run";
         case "work-item": return "workItem";
         case "input": return "inputRequest";
         case "message": return "message";

package/dist/coordination/workMailboxQueue.js

@@ -1,5 +1,5 @@
 import { completeProcessing, consumePendingBatch, createWorkMailbox, enqueueSignal, mailboxBatches, mailboxEntityRefKey } from "./workMailbox.js";
-const LEGACY_ROLE_TURN_DISPATCH_REASONS = new Set([
+const LEGACY_ROLE_RUN_DISPATCH_REASONS = new Set([
     "turn-dispatched",
     "turn-retried",
     "review-requested",
@@ -19,34 +19,33 @@ export function enqueueWork(store, target, reason, occurredAt, refs = [], metada
     return queued;
 }
 /**
- * The sole ordinary Role Turn wake shape. The Turn is durable execution
- * authority; this signal only asks the Controller to deliver that exact Turn.
+ * The sole ordinary Role AgentRun wake shape. The AgentRun is durable execution
+ * authority; this signal only asks the Controller to deliver that exact AgentRun.
  * Leader is deliberately excluded because its Role mailbox is reserved for
- * semantic event wakes and force-steer batches. A Leader active Turn is
+ * semantic event wakes and force-steer batches. A Leader active AgentRun is
  * selected directly from durable state by its targeted Controller pass.
  */
-export function enqueueRoleTurnDispatch(store, input) {
+export function enqueueRoleRunDispatch(store, input) {
     if (input.roleName === "leader")
         return null;
-    return enqueueWork(store, roleTurnTarget(input), input.reason, input.occurredAt, [roleTurnRef(input)], {
+    return enqueueWork(store, roleRunTarget(input), input.reason, input.occurredAt, [roleRunRef(input)], {
         source: "turn-dispatch",
-        dedupeKey: roleTurnDispatchDedupeKey(input)
+        dedupeKey: roleRunDispatchDedupeKey(input)
     });
 }
 /**
- * Captures only the mailbox prefix that contains one exact Role Turn dispatch.
+ * Captures only the mailbox prefix that contains one exact Role AgentRun dispatch.
  * A later signal may append while Provider delivery is in flight; its suffix
  * remains pending when this token is settled.
  */
-export function captureRoleTurnDispatch(mailbox, input) {
-    if (input.roleName === "leader"
-        || mailbox === null
+export function captureRoleRunDispatch(mailbox, input) {
+    if (mailbox === null
         || mailbox.target.kind !== "role"
         || mailbox.target.taskId !== input.taskId
         || mailbox.target.roleName !== input.roleName) {
         return null;
     }
-    const exactRef = roleTurnRef(input);
+    const exactRef = roleRunRef(input);
     if (mailbox.processing?.executionRef !== undefined
         && mailboxEntityRefKey(mailbox.processing.executionRef) === mailboxEntityRefKey(exactRef)) {
         return {
@@ -54,30 +53,34 @@ export function captureRoleTurnDispatch(mailbox, input) {
             batchId: mailbox.processing.batchId
         };
     }
+    // A Leader's initial planning batch may be explicitly bound to its Run.
+    // Never infer a Leader dispatch from pending semantic notifications.
+    if (input.roleName === "leader")
+        return null;
     const pending = mailbox.pending;
     if (pending === null)
         return null;
-    const dedupeKey = roleTurnDispatchDedupeKey(input);
+    const dedupeKey = roleRunDispatchDedupeKey(input);
     if (mailbox.recentDedupeKeys.includes(dedupeKey))
         return null;
     const keyIndex = pending.dedupeKeys.indexOf(dedupeKey);
     if (keyIndex >= 0 && pending.dedupeKeys.length === pending.requestCount) {
-        const turnSequence = pending.fromSequence + keyIndex;
-        if (turnSequence <= pending.toSequence) {
+        const runSequence = pending.fromSequence + keyIndex;
+        if (runSequence <= pending.toSequence) {
             return {
                 kind: "pending",
                 fromSequence: pending.fromSequence,
-                toSequence: turnSequence
+                toSequence: runSequence
             };
         }
     }
     // Valid earlier dispatches used sequence-generated dedupe keys and could
     // include a companion WorkItem ref. Consume that complete legacy batch once
-    // the exact Turn reaches an accepted or terminal boundary.
+    // the exact AgentRun reaches an accepted or terminal boundary.
     if (pending.requestCount === 1
         && pending.sources.length === 1
         && pending.sources[0] === "yui"
-        && pending.reasons.some((reason) => LEGACY_ROLE_TURN_DISPATCH_REASONS.has(reason))
+        && pending.reasons.some((reason) => LEGACY_ROLE_RUN_DISPATCH_REASONS.has(reason))
         && pending.refs.some((ref) => (mailboxEntityRefKey(ref) === mailboxEntityRefKey(exactRef)))) {
         return {
             kind: "pending",
@@ -88,19 +91,19 @@ export function captureRoleTurnDispatch(mailbox, input) {
     return null;
 }
 /**
- * Settles one exact ordinary Role Turn dispatch. Provider acceptance is the
+ * Settles one exact ordinary Role AgentRun dispatch. Provider acceptance is the
  * normal boundary; terminalization calls the same operation for conclusively
  * unaccepted and valid earlier dispatches.
  */
-export function settleRoleTurnDispatch(store, input, expected) {
+export function settleRoleRunDispatch(store, input, expected) {
     if (expected === null)
         return "absent";
-    const target = roleTurnTarget(input);
+    const target = roleRunTarget(input);
     const mailbox = store.getWorkMailbox(target);
-    const current = captureRoleTurnDispatch(mailbox, input);
+    const current = captureRoleRunDispatch(mailbox, input);
     if (current === null || mailbox === null)
         return "absent";
-    if (expected !== undefined && !sameRoleTurnDispatchToken(current, expected)) {
+    if (expected !== undefined && !sameRoleRunDispatchToken(current, expected)) {
         return "state-changed";
     }
     const token = expected ?? current;
@@ -135,9 +138,9 @@ export function completeWorkExecution(store, target, executionRef) {
 /**
  * Completes a mailbox execution or fails the surrounding transaction.
  *
- * A terminal Turn and its processing mailbox batch are one consistency
+ * A terminal AgentRun and its processing mailbox batch are one consistency
  * boundary. Silently accepting a missing or mismatched batch would leave
- * durable work stuck in `processing` after the Turn has already ended.
+ * durable work stuck in `processing` after the AgentRun has already ended.
  */
 export function requireCompleteWorkExecution(store, target, executionRef) {
     const mailbox = store.getWorkMailbox(target);
@@ -156,7 +159,7 @@ export function requireCompleteWorkExecution(store, target, executionRef) {
         + `${executionRef.type}/${executionRef.id}.`);
 }
 /**
- * Settles the exact Turn delivery boundary, including the short window before
+ * Settles the exact AgentRun delivery boundary, including the short window before
  * the scheduler has claimed its single pending dispatch. A merged pending
  * batch is never discarded because its signal-to-ref mapping is no longer
  * recoverable.
@@ -183,24 +186,24 @@ export function settleExactWorkExecution(store, target, executionRef) {
 function timestamp(value) {
     return value instanceof Date ? value.toISOString() : value;
 }
-function roleTurnTarget(input) {
+function roleRunTarget(input) {
     return {
         kind: "role",
         taskId: input.taskId,
         roleName: input.roleName
     };
 }
-function roleTurnRef(input) {
+function roleRunRef(input) {
     return {
-        type: "turn",
+        type: "run",
         taskId: input.taskId,
-        id: input.turnId
+        id: input.runId
     };
 }
-function roleTurnDispatchDedupeKey(input) {
-    return `role-turn:${input.taskId}:${input.roleName}:${input.turnId}`;
+function roleRunDispatchDedupeKey(input) {
+    return `role-turn:${input.taskId}:${input.roleName}:${input.runId}`;
 }
-function sameRoleTurnDispatchToken(left, right) {
+function sameRoleRunDispatchToken(left, right) {
     return left.kind === right.kind
         && (left.kind === "pending"
             ? right.kind === "pending"

package/dist/core/boundedRpc.js

@@ -145,10 +145,15 @@ export class BoundedRpcClient {
     }
     #newReadyPromise() {
         this.#readyFired = false;
-        return new Promise((resolve, reject) => {
+        const ready = new Promise((resolve, reject) => {
             this.#readyResolve = resolve;
             this.#readyReject = reject;
         });
+        // Closing during startup is legal even if no request has awaited ready.
+        // Observe that rejection without replacing the original promise: send()
+        // still receives the failure instead of an invented ready worker.
+        void ready.catch(() => undefined);
+        return ready;
     }
     #workerUrl() {
         return this.#workerScript instanceof URL
@@ -219,6 +224,8 @@ export class BoundedRpcClient {
             }
             // Brief backoff to avoid a hot crash loop.
             await new Promise((resolve) => setTimeout(resolve, this.#restartBackoffMs));
+            if (this.#closed)
+                return;
             this.#generation += 1;
             this.#port?.close();
             this.#ready = this.#newReadyPromise();

package/dist/core/controllerClient.js

@@ -102,7 +102,7 @@ export async function callController(home, method, params = {}, options = {}) {
  * Home identity, PID, and process-start identity; an unprovable process is
  * never touched.
  */
-export async function stopOrphanedFileTaskController(home, timeoutMs) {
+export async function stopOrphanedFileTaskController(home, timeoutMs, options = {}) {
     if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
         throw new TypeError("Controller timeout must be a positive integer.");
     }
@@ -110,6 +110,11 @@ export async function stopOrphanedFileTaskController(home, timeoutMs) {
     const candidate = findLiveControllerProcessForHome(homeFilesystemId);
     if (candidate === undefined)
         return undefined;
+    if ((options.expectedPid !== undefined && candidate.pid !== options.expectedPid)
+        || (options.expectedProcessStartIdentity !== undefined
+            && candidate.processStartIdentity !== options.expectedProcessStartIdentity)) {
+        throw new Error("Controller ownership changed before physical recovery.");
+    }
     if (inspectLiveControllerProcess(candidate.pid, homeFilesystemId, candidate.processStartIdentity) === undefined)
         return undefined;
     try {
@@ -121,7 +126,21 @@ export async function stopOrphanedFileTaskController(home, timeoutMs) {
         throw error;
     }
     const deadline = Date.now() + timeoutMs;
+    const forceAt = Date.now() + Math.min(1000, timeoutMs / 2);
+    let forced = false;
     while (inspectLiveControllerProcess(candidate.pid, homeFilesystemId, candidate.processStartIdentity) !== undefined) {
+        if (options.force && !forced && Date.now() >= forceAt) {
+            // The loop revalidates UID, entrypoint, Home and process start identity
+            // immediately before escalation. Never signal a successor Controller.
+            try {
+                process.kill(candidate.pid, "SIGKILL");
+            }
+            catch (error) {
+                if (!isNodeError(error) || error.code !== "ESRCH")
+                    throw error;
+            }
+            forced = true;
+        }
         if (Date.now() >= deadline) {
             throw new ControllerClientError("CONTROLLER_TIMEOUT", `Orphaned Controller did not stop within ${timeoutMs} ms.`);
         }