@zq-silk/yui 0.15.7 → 0.15.9

package/dist/controller/runtimeLaunchCoordinator.js

@@ -1,472 +1,126 @@
-import { randomUUID } from "node:crypto";
-import { runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
-import { createRuntimeBinding, RuntimeGenerationMismatchError, RuntimeHostContentionError, RuntimeHostUnavailableError, RuntimeLaunchError } from "../runtime/index.js";
+import { createRuntimeBinding } from "../runtime/index.js";
 import { sameEffectiveLaunch, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
-class RuntimeBindingContractError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = "RuntimeBindingContractError";
-    }
-}
-class RuntimeLaunchStateChangedError extends Error {
-    constructor(message, options) {
-        super(message, options);
-        this.name = "RuntimeLaunchStateChangedError";
-    }
-}
-/**
- * One application service owns the reservation -> host -> persistence
- * protocol for Controller/scheduler-driven Role launches. Foreground Task
- * attach is deliberately outside this lifecycle boundary.
- */
+/** Serialize local Role launches; failures preserve resources for explicit recovery. */
 export class RuntimeLaunchCoordinator {
-    reservations;
+    sessions;
     host;
-    #createGenerationId;
-    #now;
-    #assertCurrent;
-    #onCleanupRequired;
-    #runtimeIsolation;
-    constructor(reservations, host, options = {}) {
-        this.reservations = reservations;
+    options;
+    #launchTails = new Map();
+    constructor(sessions, host, options = {}) {
+        this.sessions = sessions;
         this.host = host;
-        this.#createGenerationId = options.createGenerationId ?? randomUUID;
-        this.#now = options.now ?? (() => new Date());
-        this.#assertCurrent = options.assertCurrent;
-        this.#onCleanupRequired = options.onCleanupRequired;
-        this.#runtimeIsolation = options.runtimeIsolation;
+        this.options = options;
     }
-    async prepare(request, persistence, assertCurrent, beforeHostStart) {
-        const ownerKey = request.owner.scope === "task"
+    async prepare(request, assertCurrent, beforeHostStart) {
+        const key = request.owner.scope === "task"
             ? `task\0${request.owner.taskId}\0${request.owner.roleName}`
             : `global\0${request.owner.roleName}`;
-        const previous = this.#launchTails.get(ownerKey) ?? Promise.resolve();
+        const previous = this.#launchTails.get(key) ?? Promise.resolve();
         let release;
         const current = new Promise((resolve) => { release = resolve; });
         const tail = previous.then(() => current);
-        this.#launchTails.set(ownerKey, tail);
+        this.#launchTails.set(key, tail);
         await previous;
         try {
-            return await this.#prepareUnlocked(request, persistence, assertCurrent, beforeHostStart);
+            return await this.#launch(request, assertCurrent, beforeHostStart);
         }
         finally {
             release();
-            if (this.#launchTails.get(ownerKey) === tail) {
-                this.#launchTails.delete(ownerKey);
-            }
+            if (this.#launchTails.get(key) === tail)
+                this.#launchTails.delete(key);
         }
     }
-    #launchTails = new Map();
-    async #prepareUnlocked(request, persistence, assertCurrent, beforeHostStart) {
+    async #launch(request, assertCurrent, beforeHostStart) {
         const effective = validateEffectiveLaunchSnapshot(request.effective);
         if (effective.agentId !== request.agentId
             || effective.adapterId !== request.adapterId
             || effective.workspace.root !== request.workspace) {
-            throw new TypeError("Runtime launch request does not match its effective snapshot.");
-        }
-        if (this.#runtimeIsolation !== undefined && request.owner.scope === "task") {
-            if (request.managedWorkspace === undefined) {
-                throw new Error("An authoritative ManagedWorkspace owner is required for a Task runtime launch.");
-            }
-            if (request.managedWorkspace.owner.taskId !== request.owner.taskId
-                || request.managedWorkspace.root !== request.workspace) {
-                throw new Error("Task runtime launch does not match its authoritative ManagedWorkspace.");
-            }
+            throw new TypeError("Runtime launch does not match its effective configuration.");
         }
         if (request.owner.scope === "global" && request.managedWorkspace !== undefined) {
             throw new Error("A global runtime cannot use a Task ManagedWorkspace.");
         }
-        let currentRequest = request;
         const assertLaunchCurrent = () => {
-            this.#assertCurrent?.(currentRequest);
+            this.options.assertCurrent?.(request);
             assertCurrent?.();
         };
-        const proposedGenerationId = requireText(this.#createGenerationId(), "Launch generation id");
-        // A Host activation id is an opaque durable identity, not a digest of the
-        // launch configuration. Whether a live activation may be reused is answered
-        // by the Role's durable Session record through `assertCurrent`, so launch
-        // configuration that only shapes the next activation never invalidates the
-        // current one.
-        let proposedRuntimeGenerationId = `runtime-${proposedGenerationId}`;
-        let reusedConfirmedRunningHost = false;
-        if (request.mode === "resume" && request.hostActivationId !== undefined) {
-            const inspection = await this.host.inspectOwner(request.owner);
-            if (inspection.state === "unavailable" || inspection.state === "starting") {
-                throw new RuntimeLaunchError(true, request.hostActivationId, `Host activation is temporarily ${inspection.state}: ${request.owner.roleName}.`);
-            }
-            if (inspection.state === "running") {
-                proposedRuntimeGenerationId = request.hostActivationId;
-                reusedConfirmedRunningHost = true;
-            }
-        }
-        let runtimeIsolation = reusedConfirmedRunningHost
-            ? undefined
-            : this.#preflightRuntimeIsolation(request, proposedRuntimeGenerationId, proposedGenerationId, false);
-        let reservation = this.reservations.reserveRuntimeLaunch({
-            owner: request.owner,
-            runtimeGenerationId: proposedRuntimeGenerationId
-        }, assertLaunchCurrent, this.#now());
-        if (reservation.status === "existing") {
-            const inspection = await this.host.inspectOwner(request.owner);
-            if (inspection.state === "unavailable" || inspection.state === "starting") {
-                throw new RuntimeLaunchError(true, reservation.runtimeGenerationId, `Runtime is temporarily ${inspection.state}: ${request.owner.roleName}/${reservation.runtimeGenerationId}.`);
-            }
-            if (inspection.state === "stopped") {
-                const taskOwner = request.owner.scope === "task"
-                    ? request.owner
-                    : undefined;
-                let exactCleanupAttempted = false;
-                let completed = false;
-                try {
-                    completed = this.reservations.completeRuntimeLaunchReservation(request.owner, reservation.runtimeGenerationId, taskOwner !== undefined && this.#runtimeIsolation !== undefined
-                        ? () => {
-                            exactCleanupAttempted = true;
-                            this.#cleanupTaskLaunch(taskOwner, reservation.runtimeGenerationId);
-                        }
-                        : undefined);
-                }
-                catch (error) {
-                    if (exactCleanupAttempted)
-                        this.#requireCleanup(request.owner);
-                    throw error;
-                }
-                if (!completed) {
-                    if (exactCleanupAttempted)
-                        this.#requireCleanup(request.owner);
-                    throw new Error("Runtime launch reservation changed during recovery.");
-                }
-                reservation = this.reservations.reserveRuntimeLaunch({
-                    owner: request.owner,
-                    runtimeGenerationId: proposedRuntimeGenerationId
-                }, assertLaunchCurrent, this.#now());
-                if (reservation.status !== "reserved") {
-                    throw new Error("Runtime launch reservation could not be renewed.");
+        assertLaunchCurrent();
+        let isolation;
+        if (request.owner.scope === "task" && this.options.runtimeIsolation !== undefined) {
+            const workspace = request.managedWorkspace;
+            // A Task that legitimately owns no workspace has nothing to isolate: an
+            // empty environment plan over no bound Project (S27). Skipping isolation
+            // here is what lets such a Leader launch at all; a *missing*
+            // authoritative workspace still fails closed below.
+            if (request.workspaceFree === true) {
+                if (workspace !== undefined) {
+                    throw new Error("A workspace-free Task launch cannot carry a ManagedWorkspace.");
                 }
             }
+            else if (workspace === undefined || workspace.owner.taskId !== request.owner.taskId
+                || workspace.root !== request.workspace) {
+                throw new Error("Task launch requires its authoritative ManagedWorkspace.");
+            }
             else {
-                reusedConfirmedRunningHost = true;
-                runtimeIsolation = undefined;
-                assertLaunchCurrent();
+                isolation = this.options.runtimeIsolation.preflight({
+                    workspace,
+                    ...(request.runtimePolicy === undefined ? {} : { policy: request.runtimePolicy }),
+                    allowExactActive: true
+                });
+                this.options.runtimeIsolation.activate(isolation);
             }
         }
-        const runtimeGenerationId = reservation.runtimeGenerationId;
         let preflightObserved = beforeHostStart === undefined;
         const observePreflight = (preflight) => {
-            if (preflightObserved) {
-                throw new Error("Runtime host reported its pre-start launch fence more than once.");
+            if (preflightObserved || !sameOwner(preflight.owner, request.owner)
+                || preflight.runId !== request.runId
+                || preflight.agentId !== request.agentId
+                || preflight.adapterId !== request.adapterId
+                || !sameEffectiveLaunch(preflight.effective, request.effective)
+                || (request.mode === "resume" && preflight.nativeSessionId !== request.nativeSessionId)) {
+                throw new Error("Session host pre-start facts do not match the requested launch.");
             }
-            validateRuntimeLaunchPreflight(preflight, request, runtimeGenerationId);
-            this.reservations.confirmRuntimeLaunchReservation({
-                owner: request.owner,
-                runtimeGenerationId
-            }, assertLaunchCurrent);
+            assertLaunchCurrent();
             preflightObserved = true;
             beforeHostStart?.(preflight);
-            // The pre-start persistence callback hands the fixed native Session to
-            // this reserved activation. From here on, fence against that exact new
-            // identity, not the historical Host we originally set out to restore.
-            // Do not accept both identities: a later change back is stale as well.
-            if (request.mode === "resume" && request.hostActivationId !== undefined) {
-                currentRequest = { ...request, hostActivationId: runtimeGenerationId };
-            }
-            assertLaunchCurrent();
         };
-        let binding;
-        try {
-            if (!reusedConfirmedRunningHost && runtimeIsolation !== undefined) {
-                // Activation is the first runtime-resource side effect and can occur
-                // only after the centralized read-only preflight and durable launch
-                // reservation have both succeeded.
-                this.#runtimeIsolation.activate(runtimeIsolation);
-            }
-            const rawBinding = request.mode === "new"
-                ? await this.host.start({
-                    mode: "new",
-                    runtimeGenerationId,
-                    owner: request.owner,
-                    agentId: request.agentId,
-                    adapterId: request.adapterId,
-                    effective: request.effective,
-                    workspace: request.workspace,
-                    ...(runtimeIsolation === undefined
-                        ? {}
-                        : { runtimeIsolation: runtimeIsolation.descriptor }),
-                    ...(request.turnId === undefined ? {} : { turnId: request.turnId }),
-                    ...(request.environment === undefined
-                        ? {}
-                        : { environment: request.environment })
-                }, beforeHostStart === undefined ? undefined : observePreflight)
-                : await this.host.restore({
-                    mode: "resume",
-                    runtimeGenerationId,
-                    owner: request.owner,
-                    agentId: request.agentId,
-                    adapterId: request.adapterId,
-                    effective: request.effective,
-                    workspace: request.workspace,
-                    ...(runtimeIsolation === undefined
-                        ? {}
-                        : { runtimeIsolation: runtimeIsolation.descriptor }),
-                    ...(request.turnId === undefined ? {} : { turnId: request.turnId }),
-                    ...(request.environment === undefined
-                        ? {}
-                        : { environment: request.environment }),
-                    nativeSessionId: requireText(request.nativeSessionId, "Native session id")
-                }, beforeHostStart === undefined ? undefined : observePreflight);
-            binding = requireMatchingRuntimeBinding(rawBinding, request, runtimeGenerationId);
-            if (!preflightObserved) {
-                throw new Error("Runtime session host did not expose a pre-host-start launch fence.");
-            }
-        }
-        catch (error) {
-            if (error instanceof RuntimeHostUnavailableError) {
-                // A failed reused attachment provides no authority to detach its
-                // native Conversation or schedule owner-wide physical cleanup.
-                throw error;
-            }
-            if (error instanceof RuntimeGenerationMismatchError) {
-                // The observed Host is not the requested activation. Neither killing
-                // it nor scheduling owner-wide cleanup is justified by that conflict.
-                throw new RuntimeLaunchError(false, runtimeGenerationId, error.message, "generation-mismatch", { cause: error });
-            }
-            if (error instanceof RuntimeHostContentionError && reusedConfirmedRunningHost) {
-                // The exact recovered generation remains authoritative. A late human
-                // writer is transient backpressure and must not settle, clean, or
-                // terminalize that reservation.
-                throw new RuntimeLaunchError(true, runtimeGenerationId, error.message, error.reason, { cause: error });
-            }
-            if (error instanceof RuntimeHostContentionError
-                && !reusedConfirmedRunningHost) {
-                let exactCleanupAttempted = false;
-                let completed = false;
-                try {
-                    completed = this.reservations.completeRuntimeLaunchReservation(request.owner, runtimeGenerationId, runtimeIsolation === undefined
-                        ? undefined
-                        : () => {
-                            exactCleanupAttempted = true;
-                            this.#runtimeIsolation.cleanup(runtimeIsolation, "failure");
-                        });
-                }
-                catch (cleanupError) {
-                    if (exactCleanupAttempted)
-                        this.#requireCleanup(request.owner);
-                    throw cleanupError;
-                }
-                if (!completed) {
-                    this.#requireCleanup(request.owner);
-                    throw new Error("Busy managed runtime launch reservation changed during retry release.");
-                }
-                throw new RuntimeLaunchError(true, runtimeGenerationId, error.message, error instanceof RuntimeHostContentionError
-                    ? error.reason
-                    : "previous-process", { cause: error });
-            }
-            if (error instanceof RuntimeBindingContractError) {
-                // Never pass an untrusted hostRef to stop(). Reconcile the requested
-                // owner through the durable, owner-addressed cleanup lane instead.
-                this.#requireCleanup(request.owner);
-                throw error;
-            }
-            await this.#settleFailedStart(request, runtimeGenerationId, reusedConfirmedRunningHost, runtimeIsolation);
-            throw error;
-        }
-        if (reusedConfirmedRunningHost && binding.hostCreated === true) {
-            await this.#compensateStartedHost(request.owner, binding, runtimeGenerationId, runtimeIsolation, reusedConfirmedRunningHost, new Error(`Runtime host was recreated while recovering an existing generation: ${request.owner.roleName}.`));
-        }
-        try {
-            assertLaunchCurrent();
-            const reservationState = this.reservations.confirmRuntimeLaunchReservation({
-                owner: request.owner,
-                runtimeGenerationId
-            }, assertLaunchCurrent);
-            if (reservationState === "reserved") {
-                if (binding.nativeSessionId !== undefined) {
-                    this.reservations.recordReservedRuntimeNativeSession({
-                        owner: request.owner,
-                        runtimeGenerationId,
-                        agentId: request.agentId,
-                        adapterId: request.adapterId,
-                        nativeSessionId: binding.nativeSessionId,
-                        effective: request.effective
-                    }, assertLaunchCurrent, this.#now());
-                }
-                else if (!this.reservations.completeRuntimeLaunchReservation(request.owner, runtimeGenerationId)) {
-                    throw new Error("Runtime Host-start reservation changed before completion.");
-                }
-            }
-        }
-        catch (error) {
-            await this.#compensateStartedHost(request.owner, binding, runtimeGenerationId, runtimeIsolation, reusedConfirmedRunningHost, error);
-        }
-        return binding;
-    }
-    async #settleFailedStart(request, runtimeGenerationId, reusedConfirmedRunningHost, runtimeIsolation) {
-        let inspection;
-        try {
-            inspection = await this.host.inspectOwner(request.owner);
-        }
-        catch {
-            // A rebind/preflight failure did not create the already-confirmed host.
-            // Preserve its generation when the follow-up probe is merely unknown.
-            if (!reusedConfirmedRunningHost)
-                this.#requireCleanup(request.owner);
-            return;
-        }
-        if (inspection.state === "stopped") {
-            if (runtimeIsolation !== undefined) {
-                try {
-                    this.#runtimeIsolation.cleanup(runtimeIsolation, "failure");
-                }
-                catch (cleanupError) {
-                    this.#requireCleanup(request.owner);
-                    throw new Error(`Task runtime launch failed and exact resource cleanup also failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`, { cause: cleanupError });
-                }
-            }
-            if (!this.#settleConfirmedStopped(request, runtimeGenerationId)) {
-                this.#requireCleanup(request.owner);
-            }
-            return;
-        }
-        if (reusedConfirmedRunningHost)
-            return;
-        this.#requireCleanup(request.owner);
-    }
-    async #compensateStartedHost(owner, binding, runtimeGenerationId, runtimeIsolation, reusedConfirmedRunningHost, cause) {
-        if (reusedConfirmedRunningHost && binding.hostCreated !== true) {
-            // Reattaching an existing activation gives this launch no ownership of
-            // it. A fresh activation inside a persistent Host is different: this
-            // launch still owns its startup and isolation cleanup even when the
-            // physical Host did not need to be created.
-            throw new RuntimeLaunchStateChangedError(`Runtime launch state changed while reusing a Host: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
-        }
-        try {
-            await this.host.stop(binding);
-        }
-        catch (stopError) {
-            this.#requireCleanup(owner);
-            throw new Error(`Runtime launch state changed. Runtime cleanup also failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`, { cause: stopError });
-        }
-        let stopped = false;
-        try {
-            stopped = (await this.host.inspectOwner(owner)).state === "stopped";
-        }
-        catch {
-            // Durable owner cleanup below is the only safe fallback.
-        }
-        if (stopped && runtimeIsolation !== undefined) {
-            try {
-                this.#runtimeIsolation.cleanup(runtimeIsolation, "failure");
-            }
-            catch (cleanupError) {
-                this.#requireCleanup(owner);
-                throw new Error(`Runtime host stopped but exact Task resource cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`, { cause: cleanupError });
-            }
-        }
-        if (!stopped
-            || !this.reservations.settleStoppedRuntimeLaunch({
-                owner,
-                runtimeGenerationId,
-                agentId: binding.agentId,
-                adapterId: binding.adapterId,
-                ...(binding.nativeSessionId === undefined
-                    ? {}
-                    : { nativeSessionId: binding.nativeSessionId })
-            }, this.#now())) {
-            this.#requireCleanup(owner);
-        }
-        const detail = cause instanceof Error ? cause.message : String(cause);
-        throw new RuntimeLaunchStateChangedError(`Runtime launch was compensated after state changed: ${detail}`, { cause });
-    }
-    #preflightRuntimeIsolation(request, runtimeGenerationId, generationId, allowExactActive) {
-        if (this.#runtimeIsolation === undefined || request.owner.scope !== "task") {
-            return undefined;
-        }
-        return this.#runtimeIsolation.preflight({
-            workspace: request.managedWorkspace,
-            runtimeGenerationId,
-            generationId: requireText(generationId, "Launch generation id"),
-            ...(request.runtimePolicy === undefined ? {} : { policy: request.runtimePolicy }),
-            ...(allowExactActive ? { allowExactActive: true } : {})
-        });
-    }
-    #cleanupTaskLaunch(owner, runtimeGenerationId) {
-        const cleanupTaskLaunch = this.#runtimeIsolation?.cleanupTaskLaunch;
-        if (cleanupTaskLaunch === undefined) {
-            throw new Error("Exact Task runtime launch cleanup is unavailable.");
-        }
-        cleanupTaskLaunch.call(this.#runtimeIsolation, {
-            taskId: owner.taskId,
-            runtimeGenerationId,
-            reason: "interruption"
-        });
-    }
-    #settleConfirmedStopped(request, runtimeGenerationId) {
-        return this.reservations.settleStoppedRuntimeLaunch({
+        const shared = {
             owner: request.owner,
-            runtimeGenerationId,
             agentId: request.agentId,
             adapterId: request.adapterId,
-            ...(request.nativeSessionId === undefined
-                ? {}
-                : { nativeSessionId: request.nativeSessionId })
-        }, this.#now());
-    }
-    #requireCleanup(owner) {
-        const target = this.reservations.enqueueRuntimeCleanup(owner, this.#now())
-            ?? runtimeLifecycleTarget(owner);
-        try {
-            this.#onCleanupRequired?.(target);
-        }
-        catch {
-            // The durable cleanup lane is authoritative.
+            effective,
+            workspace: request.workspace,
+            ...(isolation === undefined ? {} : { runtimeIsolation: isolation.descriptor }),
+            ...(request.runId === undefined ? {} : { runId: request.runId }),
+            ...(request.environment === undefined ? {} : { environment: request.environment })
+        };
+        const callback = beforeHostStart === undefined ? undefined : observePreflight;
+        if (request.mode === "resume" && !request.nativeSessionId) {
+            throw new Error("Restoring a Session requires its native session id.");
+        }
+        const binding = createRuntimeBinding(request.mode === "new"
+            ? await this.host.start({ ...shared, mode: "new" }, callback)
+            : await this.host.restore({
+                ...shared, mode: "resume", nativeSessionId: request.nativeSessionId
+            }, callback));
+        if (!preflightObserved || !sameOwner(binding.owner, request.owner)
+            || binding.agentId !== request.agentId || binding.adapterId !== request.adapterId
+            || (request.mode === "resume" && binding.nativeSessionId !== request.nativeSessionId)) {
+            throw new Error("Session host returned facts inconsistent with the requested launch.");
+        }
+        if (binding.nativeSessionId !== undefined) {
+            this.sessions.recordLaunchedRuntimeNativeSession({
+                owner: request.owner,
+                agentId: request.agentId,
+                adapterId: request.adapterId,
+                nativeSessionId: binding.nativeSessionId,
+                effective
+            }, assertLaunchCurrent, this.options.now?.() ?? new Date());
         }
+        return binding;
     }
 }
-function validateRuntimeLaunchPreflight(preflight, request, runtimeGenerationId) {
-    const ownerMatches = preflight.owner.scope === request.owner.scope
-        && preflight.owner.roleName === request.owner.roleName
-        && (preflight.owner.scope === "global"
-            || (request.owner.scope === "task"
-                && preflight.owner.taskId === request.owner.taskId));
-    if (preflight.runtimeGenerationId !== runtimeGenerationId
-        || !ownerMatches
-        || preflight.turnId !== request.turnId
-        || preflight.agentId !== request.agentId
-        || preflight.adapterId !== request.adapterId
-        || !sameEffectiveLaunch(preflight.effective, request.effective)
-        || (request.mode === "resume"
-            && preflight.nativeSessionId !== request.nativeSessionId)) {
-        throw new Error(`Session host pre-start launch fence does not match the requested runtime: ${request.owner.roleName}.`);
-    }
-}
-function requireMatchingRuntimeBinding(raw, request, runtimeGenerationId) {
-    let binding;
-    try {
-        binding = createRuntimeBinding(raw);
-    }
-    catch (error) {
-        throw new RuntimeBindingContractError("Session host returned an invalid runtime binding.", { cause: error });
-    }
-    const ownerMatches = binding.owner.scope === request.owner.scope
-        && binding.owner.roleName === request.owner.roleName
-        && (binding.owner.scope === "global"
-            || (request.owner.scope === "task"
-                && binding.owner.taskId === request.owner.taskId));
-    if (binding.runtimeGenerationId !== runtimeGenerationId
-        || !ownerMatches
-        || binding.agentId !== request.agentId
-        || binding.adapterId !== request.adapterId
-        || (request.mode === "resume"
-            && binding.nativeSessionId !== request.nativeSessionId)) {
-        throw new RuntimeBindingContractError(`Session host returned a binding that does not match the requested runtime: ${request.owner.roleName}.`);
-    }
-    return binding;
-}
-function requireText(value, label) {
-    if (typeof value !== "string"
-        || value.length === 0
-        || value.trim() !== value
-        || value.includes("\0")) {
-        throw new Error(`${label} is invalid.`);
-    }
-    return value;
+function sameOwner(a, b) {
+    return a.scope === b.scope && a.roleName === b.roleName
+        && (a.scope === "global" || (b.scope === "task" && a.taskId === b.taskId));
 }

package/dist/controller/runtimeObservationHook.js

@@ -3,18 +3,18 @@ import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { normalizeAgentDriverHookClassification } from "../runtime/agentDriver.js";
 import { mapAgentDriverHooks } from "../runtime/agentDriverObservation.js";
 import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
-import { formatTurnReceiptId } from "../task/taskRecordReference.js";
-import { boundedTurnFailureDiagnostic, transportAgentResult } from "../domain/agentResultTransport.js";
+import { formatRunReceiptId } from "../task/taskRecordReference.js";
+import { boundedRunFailureDiagnostic, transportAgentResult } from "../domain/agentResultTransport.js";
 import { FileRuntimeEventInbox, MAX_RUNTIME_EVENT_FILE_BYTES } from "./runtimeEventInbox.js";
-import { resolveRuntimeHookTurnFence } from "./runtimeHookTurnFence.js";
+import { resolveRuntimeHookRunFence } from "./runtimeHookRunFence.js";
 /**
  * Single hidden ingress for every structured CLI Driver Hook. Native event
  * names and payload shapes terminate here; the durable inbox contains only a
- * provider-independent RuntimeObservation with an exact generation/Turn fence.
+ * provider-independent RuntimeObservation with an exact Session/AgentRun fence.
  */
 export async function runRuntimeObservationHookCommand(stdinJson, environment = process.env, call = callController, now = new Date(), dependencies = {}) {
     if (environment.YUI_SESSION_SCOPE === "global") {
-        await runGlobalRuntimeTurnHook(stdinJson, environment, call, now, dependencies);
+        await runGlobalRuntimeRunHook(stdinJson, environment, call, now, dependencies);
         return;
     }
     const parsed = parseRuntimeObservationHook(stdinJson, environment, now, dependencies);
@@ -33,7 +33,7 @@ export async function runRuntimeObservationHookCommand(stdinJson, environment =
         })
     }, { timeoutMs: 100 }).catch(() => { });
 }
-async function runGlobalRuntimeTurnHook(stdinJson, environment, call, now, dependencies) {
+async function runGlobalRuntimeRunHook(stdinJson, environment, call, now, dependencies) {
     const payload = parseObject(stdinJson);
     const hookEventName = requireIdentity(payload.hook_event_name, "Agent Driver Hook event name");
     if (hookEventName !== "Stop" && hookEventName !== "StopFailure")
@@ -51,12 +51,11 @@ async function runGlobalRuntimeTurnHook(stdinJson, environment, call, now, depen
     }
     const home = requireIdentity(environment.YUI_HOME, "YUI_HOME");
     const roleName = requireIdentity(environment.YUI_ROLE, "Role name");
-    new FileRuntimeEventInbox(home, () => now).enqueueTurnTerminal({
+    new FileRuntimeEventInbox(home, () => now).enqueueRunTerminal({
         scope: "global",
         roleName,
         agentId: requireIdentity(environment.YUI_AGENT_ID, "Agent id"),
         adapterId: "claude",
-        runtimeGenerationId: requireIdentity(environment.YUI_RUNTIME_GENERATION_ID, "Runtime generation id"),
         nativeSessionId,
         nativeTurnId: optionalIdentity(driver.runtime.nativeTurnId(nativeHook)) ?? occurrenceId,
         ...(environment.YUI_SESSION_TITLE === undefined
@@ -77,7 +76,7 @@ function globalHookOutcome(payload, hookEventName) {
     return {
         status: "failed",
         failureReason: "runtime-failed",
-        diagnostic: boundedTurnFailureDiagnostic(diagnostic)
+        diagnostic: boundedRunFailureDiagnostic(diagnostic)
     };
 }
 export function parseRuntimeObservationHook(stdinJson, environment, now = new Date(), dependencies = {}) {
@@ -90,7 +89,7 @@ export function parseRuntimeObservationHook(stdinJson, environment, now = new Da
         && environment.YUI_ADAPTER_ID === "claude") {
         // Existing native Conversations may retain an old Yui observer plugin.
         // Only the managed stream owns execution facts: Hooks do not expose its
-        // input attempt, and associating them with the currently active Turn can
+        // input attempt, and associating them with the currently active AgentRun can
         // steal a successor's result. This observer is not a permission handler;
         // Claude's configured tool policy and other user plugins remain intact.
         return {
@@ -107,19 +106,18 @@ export function parseRuntimeObservationHook(stdinJson, environment, now = new Da
     const nativeSessionId = requireIdentity(driver.runtime.nativeSessionId(nativeHook), "Agent Driver native Session id");
     const nativeTurnId = optionalIdentity(driver.runtime.nativeTurnId(nativeHook));
     const classification = normalizeAgentDriverHookClassification(driver.runtime.classifyHook(nativeHook));
-    const fence = (dependencies.resolveTurnFence ?? resolveRuntimeHookTurnFence)(environment, driver.adapterId, nativeSessionId, {
+    const fence = (dependencies.resolveRunFence ?? resolveRuntimeHookRunFence)(environment, driver.adapterId, nativeSessionId, {
         ...(classification.startupSession === undefined
             ? {}
             : { startupSession: classification.startupSession }),
         terminal: classification.terminal,
         ...(classification.continuationId === undefined ? {} : {
             continuationId: classification.continuationId,
-            continuationGeneration: classification.continuationGeneration ?? 1
         }),
         ...(nativeTurnId === undefined ? {} : { nativeTurnId })
     });
-    if (fence.turnId === undefined) {
-        throw new Error("Agent Driver Hook requires a managed Turn.");
+    if (fence.runId === undefined) {
+        throw new Error("Agent Driver Hook requires a managed AgentRun.");
     }
     const driverInput = {
         driver,
@@ -133,15 +131,13 @@ export function parseRuntimeObservationHook(stdinJson, environment, now = new Da
         fence: {
             taskId: fence.taskId,
             roleName: fence.roleName,
-            turnId: fence.turnId,
+            runId: fence.runId,
             agentId: fence.agentId,
             driverId,
-            runtimeGenerationId: fence.runtimeGenerationId,
             conversationId: fence.nativeSessionId,
-            activationId: fence.runtimeGenerationId,
             nativeSessionId: fence.nativeSessionId,
             ...(nativeTurnId === undefined ? {} : { nativeTurnId }),
-            receiptId: fence.receiptId ?? formatTurnReceiptId(fence.taskId, fence.turnId)
+            receiptId: fence.receiptId ?? formatRunReceiptId(fence.taskId, fence.runId)
         },
         payload
     };