@zq-silk/yui 0.6.2 → 0.6.3

package/dist/controller/runtimeHookRunFence.js

@@ -0,0 +1,226 @@
+import { openCompatibleFileTaskStore } from "../storage/compatibleTaskStore.js";
+import { hasRuntimeCleanupObligation, isRuntimeLaunchReservation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
+import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
+import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactTaskRuntimeEnvironment, exactControlPlaneDigest, parseExactControlPlaneDescriptor, refreshReusedTaskRuntimeDescriptorSource } from "../runtime/exactControlPlane.js";
+import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
+/**
+ * Resolves turn identity from the current durable in-flight fence. The one
+ * exception is a Driver-declared startup Session Hook, which can arrive before
+ * Session projection and is fenced by the exact Run-bound launch reservation.
+ * Preallocated identities are additionally checked against Yui's deterministic
+ * launch identity. The immutable event is revalidated by the inbox fold.
+ */
+export function resolveRuntimeHookRunFence(environment, adapterId, payloadNativeSessionId, options = {}) {
+    if (environment.YUI_SESSION_SCOPE !== "task") {
+        throw new Error("Runtime observation Hook requires a Task session scope.");
+    }
+    if (environment.YUI_ADAPTER_ID !== adapterId) {
+        throw new Error(`Runtime observation Hook requires the ${adapterId} adapter.`);
+    }
+    const home = requireIdentity(environment.YUI_HOME, "YUI_HOME");
+    const taskId = requireIdentity(environment.YUI_TASK_ID, "Task id");
+    const roleName = requireIdentity(environment.YUI_ROLE, "Role name");
+    const agentId = requireIdentity(environment.YUI_AGENT_ID, "Agent id");
+    const workspace = requireIdentity(environment.YUI_WORKSPACE, "YUI workspace");
+    const runtimeSource = environment[YUI_TASK_RUNTIME_DESCRIPTOR];
+    const runtime = runtimeSource === undefined
+        ? undefined
+        : assertExactTaskRuntimeEnvironment(runtimeSource, environment, exactControlPlaneDigest(parseExactControlPlaneDescriptor(requireIdentity(environment[YUI_CONTROL_PLANE_DESCRIPTOR], "Exact control-plane descriptor"))), home);
+    const launchId = requireIdentity(runtime?.launchId ?? environment.YUI_LAUNCH_ID, "Launch id");
+    const nativeSessionId = requireIdentity(payloadNativeSessionId, "Provider session id");
+    const expectedNativeSessionId = runtime?.nativeSessionId ?? environment.YUI_NATIVE_SESSION_ID;
+    if (expectedNativeSessionId !== undefined
+        && nativeSessionId !== requireIdentity(expectedNativeSessionId, "YUI native session id")) {
+        throw new Error("Runtime observation Hook native Session does not match its launch envelope.");
+    }
+    const store = openCompatibleFileTaskStore(home);
+    const task = store.getTask(taskId);
+    if (task === null || task.status !== "active") {
+        throw new Error("Runtime observation Hook Task is not current and active.");
+    }
+    const role = store.getRole(taskId, roleName);
+    if (role === null || role.activeAgentId !== agentId) {
+        throw new Error("Runtime observation Hook Role or Agent is not current.");
+    }
+    const sessions = store.getTaskRoleSessionSet(taskId, roleName);
+    if (sessions !== null && sessions.activeAgentId !== agentId) {
+        throw new Error("Runtime observation Hook Session Agent is not current.");
+    }
+    const inFlight = sessions?.inFlight;
+    const session = sessions?.sessions[agentId];
+    const acceptedBinding = options.nativeTurnId === undefined
+        ? null
+        : acceptedTurnBinding(store.listEvents(taskId), {
+            taskId,
+            roleName,
+            agentId,
+            nativeSessionId,
+            nativeTurnId: options.nativeTurnId
+        });
+    const mailbox = store.getWorkMailbox(runtimeLifecycleTarget({
+        scope: "task",
+        taskId,
+        roleName
+    }));
+    const exactReservation = isRuntimeLaunchReservation(mailbox?.processing, launchId)
+        && !hasRuntimeCleanupObligation(mailbox);
+    const executionRef = mailbox?.processing?.executionRef;
+    const startupRunId = options.startupSession === undefined
+        ? undefined
+        : requireIdentity(runtime?.runId
+            ?? environment.YUI_RUN_ID
+            ?? (executionRef?.type === "run" && executionRef.taskId === taskId
+                ? executionRef.id
+                : undefined), "Run id");
+    const startupReservation = startupRunId !== undefined
+        && exactReservation
+        && executionRef?.type === "run"
+        && executionRef.taskId === taskId
+        && executionRef.id === startupRunId;
+    const preallocatedStartup = options.startupSession === "preallocated"
+        && expectedNativeSessionId !== undefined
+        && session === undefined
+        && startupReservation
+        && nativeSessionId === nativeSessionIdForLaunch(home, launchId, agentId, adapterId);
+    const discoveredStartup = options.startupSession === "discovered"
+        && expectedNativeSessionId === undefined
+        && session === undefined
+        && startupReservation;
+    const terminalRunId = options.terminal === true && acceptedBinding === null
+        ? requireIdentity(environment.YUI_RUN_ID ?? runtime?.runId, "Run id")
+        : undefined;
+    const terminalRun = acceptedBinding !== null
+        ? store.getAgentRun(taskId, acceptedBinding.fence.runId)
+        : terminalRunId === undefined
+            ? null
+            : store.getAgentRun(taskId, terminalRunId);
+    const exactTerminal = terminalRun !== null
+        && terminalRun.status !== "active"
+        && terminalRun.roleName === roleName
+        && terminalRun.effective.agentId === agentId
+        && terminalRun.effective.adapterId === adapterId
+        && session !== undefined
+        && (acceptedBinding !== null || inFlight === null || inFlight === undefined);
+    if ((inFlight === null || inFlight === undefined)
+        && !preallocatedStartup
+        && !discoveredStartup
+        && !exactTerminal
+        && acceptedBinding === null) {
+        throw new Error("Runtime observation Hook has no matching durable in-flight Run.");
+    }
+    if (acceptedBinding === null
+        && inFlight !== null && inFlight !== undefined && inFlight.agentId !== agentId) {
+        throw new Error("Runtime observation Hook has no matching durable in-flight Run.");
+    }
+    if ((preallocatedStartup || discoveredStartup)
+        && inFlight !== null
+        && inFlight !== undefined
+        && (inFlight.runId !== startupRunId
+            || inFlight.receiptId !== formatAgentRunReceiptId(taskId, startupRunId))) {
+        throw new Error("Runtime observation Hook has no matching durable in-flight Run.");
+    }
+    const runId = acceptedBinding?.fence.runId
+        ?? inFlight?.runId
+        ?? startupRunId
+        ?? terminalRunId;
+    let effectiveRuntime = runtime;
+    let effectiveLaunchId = acceptedBinding?.fence.launchId ?? launchId;
+    const sessionLaunchId = session?.launchId;
+    if (acceptedBinding === null
+        && runtime !== undefined
+        && session !== undefined
+        && sessionLaunchId !== undefined
+        && typeof runtimeSource === "string"
+        && !runtimeSource.trimStart().startsWith("{")
+        && (runtime.runId !== runId
+            || runtime.launchId !== sessionLaunchId
+            || runtime.nativeSessionId !== session.nativeSessionId)) {
+        // A reused native pane keeps its original descriptor source. Advance only
+        // that Hook-owned source to the current durable generation before the
+        // volatile fence; the Controller no longer scans history to keep it fresh.
+        effectiveRuntime = refreshReusedTaskRuntimeDescriptorSource(runtimeSource, home, store, {
+            runId,
+            launchId: sessionLaunchId,
+            nativeSessionId: session.nativeSessionId
+        });
+        effectiveLaunchId = effectiveRuntime.launchId;
+    }
+    if (acceptedBinding === null
+        && effectiveRuntime?.runId !== undefined && effectiveRuntime.runId !== runId) {
+        throw new Error("Runtime observation Hook Run does not match its current descriptor.");
+    }
+    const run = acceptedBinding !== null || exactTerminal
+        ? terminalRun
+        : store.getActiveAgentRun(taskId, roleName);
+    if (run === null
+        || run.id !== runId
+        || (acceptedBinding === null && !exactTerminal && run.status !== "active")
+        || run.effective.agentId !== agentId
+        || run.effective.adapterId !== adapterId) {
+        throw new Error("Runtime observation Hook Run does not match durable active state.");
+    }
+    if (run.effective.workspace.root !== workspace) {
+        throw new Error("Runtime observation Hook workspace does not match the durable Run snapshot.");
+    }
+    if (session !== undefined) {
+        if (session.adapterId !== adapterId
+            || (acceptedBinding === null && session.launchId !== effectiveLaunchId)
+            || session.nativeSessionId !== nativeSessionId
+            || session.effective.workspace.root !== workspace) {
+            throw new Error("Runtime observation Hook Session does not match its durable generation.");
+        }
+    }
+    else {
+        if (!discoveredStartup && !preallocatedStartup) {
+            throw new Error("Runtime observation Hook launch is not durably reserved.");
+        }
+    }
+    return {
+        taskId,
+        roleName,
+        agentId,
+        launchId: effectiveLaunchId,
+        runId,
+        ...(acceptedBinding?.fence.receiptId === undefined
+            ? inFlight?.receiptId === undefined ? {} : { receiptId: inFlight.receiptId }
+            : { receiptId: acceptedBinding.fence.receiptId }),
+        nativeSessionId,
+        workspace
+    };
+}
+function acceptedTurnBinding(events, expected) {
+    const matches = events
+        .map(runtimeObservationFromTaskEvent)
+        .filter((observation) => observation !== null
+        && observation.kind === "turn.accepted"
+        && observation.fence.taskId === expected.taskId
+        && observation.fence.roleName === expected.roleName
+        && observation.fence.agentId === expected.agentId
+        && observation.fence.nativeSessionId === expected.nativeSessionId
+        && observation.fence.nativeTurnId === expected.nativeTurnId
+        && observation.fence.runId !== undefined)
+        .sort((left, right) => (left.receivedAt.localeCompare(right.receivedAt)
+        || (left.sequence ?? -1) - (right.sequence ?? -1)
+        || (left.ordinal ?? -1) - (right.ordinal ?? -1)
+        || left.eventId.localeCompare(right.eventId)));
+    const binding = matches.at(-1) ?? null;
+    if (binding === null)
+        return null;
+    if (matches.some((candidate) => candidate.fence.runId !== binding.fence.runId
+        || candidate.fence.launchId !== binding.fence.launchId
+        || candidate.fence.receiptId !== binding.fence.receiptId)) {
+        throw new Error("Runtime observation Hook native Turn has conflicting durable Run bindings.");
+    }
+    return binding;
+}
+function requireIdentity(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is required.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.length > 1_024) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}

package/dist/controller/runtimeLaunchCoordinator.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
-import { createRuntimeBinding, RuntimeLaunchError } from "../runtime/index.js";
+import { createRuntimeBinding, RuntimeHostContentionError, RuntimeLaunchError } from "../runtime/index.js";
 import { effectiveLaunchSnapshotsCompatible, validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
 class RuntimeBindingContractError extends Error {
     constructor(message, options) {
@@ -8,9 +8,22 @@ class RuntimeBindingContractError extends Error {
         this.name = "RuntimeBindingContractError";
     }
 }
+class LaunchSubmittedHostBusyError extends RuntimeBindingContractError {
+    constructor(message) {
+        super(message);
+        this.name = "LaunchSubmittedHostBusyError";
+    }
+}
+class RuntimeLaunchStateChangedError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RuntimeLaunchStateChangedError";
+    }
+}
 /**
  * One application service owns the reservation -> host -> persistence
- * protocol for both foreground enter and scheduler-driven Role launches.
+ * protocol for Controller/scheduler-driven Role launches. Foreground Task
+ * attach is deliberately outside this lifecycle boundary.
  */
 export class RuntimeLaunchCoordinator {
     reservations;
@@ -90,7 +103,12 @@ export class RuntimeLaunchCoordinator {
             ...(request.runId === undefined ? {} : { runId: request.runId })
         }, assertLaunchCurrent, this.#now());
         let reusedConfirmedRunningHost = false;
-        let launchPromptAcknowledgementRequired = false;
+        const launchCarriesExactRunPrompt = carriesExactRunPrompt(request);
+        // Preserve the existing Codex recovery path; managed Claude is the one
+        // finite-process protocol that must never fall back to tmux key delivery
+        // when a newly-reserved Run encounters an older live pane.
+        let launchPromptAcknowledgementRequired = request.adapterId === "claude"
+            && launchCarriesExactRunPrompt;
         if (reservation.status === "existing") {
             if (!reservation.launchId.startsWith(generationPrefix)) {
                 this.#requireCleanup(request.owner);
@@ -149,13 +167,12 @@ export class RuntimeLaunchCoordinator {
                     throw new Error(`Runtime launch reservation belongs to another Run whose host is still running: ${reservation.runId}.`);
                 }
                 reusedConfirmedRunningHost = true;
-                // Only a fresh Codex generation can carry the exact Run prompt in its
-                // launch argv. A resume request targets an existing native Session and
-                // must use the normal receipt-backed prompt push, even when the
-                // Controller is recovering the same launch reservation.
+                // A fresh Codex generation carries the prompt in its launch argv. A
+                // managed Claude generation carries it through stream-json stdin for
+                // both new and native-resume modes. Only recovery of the exact same
+                // reserved Run may bridge a lost in-memory launch acknowledgement.
                 launchPromptAcknowledgementRequired = sameRunReservation
-                    && request.mode === "new"
-                    && request.adapterId === "codex";
+                    && launchCarriesExactRunPrompt;
                 runtimeIsolation = this.#preflightRuntimeIsolation(request, reservation.launchId, reservation.launchId.slice(generationPrefix.length), true);
                 assertLaunchCurrent();
             }
@@ -212,12 +229,53 @@ export class RuntimeLaunchCoordinator {
                         : { environment: request.environment }),
                     nativeSessionId: requireText(request.nativeSessionId, "Native session id")
                 }, beforeHostStart === undefined ? undefined : observePreflight);
-            if (!preflightObserved) {
+            binding = requireMatchingRuntimeBinding(rawBinding, request, launchId, launchPromptAcknowledgementRequired, reusedConfirmedRunningHost);
+            if (!preflightObserved
+                && !(binding.hostCreated === false
+                    && request.adapterId === "claude"
+                    && launchCarriesExactRunPrompt)) {
                 throw new Error("Runtime session host did not expose a pre-host-start launch fence.");
             }
-            binding = requireMatchingRuntimeBinding(rawBinding, request, launchId, launchPromptAcknowledgementRequired, reusedConfirmedRunningHost);
         }
         catch (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, launchId, error.message, error.reason);
+            }
+            if ((error instanceof LaunchSubmittedHostBusyError
+                || error instanceof RuntimeHostContentionError)
+                && !reusedConfirmedRunningHost) {
+                let exactCleanupAttempted = false;
+                let completed = false;
+                try {
+                    completed = this.reservations.completeRuntimeLaunchReservation(request.owner, launchId, undefined, 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.");
+                }
+                if (error instanceof LaunchSubmittedHostBusyError) {
+                    // A terminal Run no longer owns its finite provider process. Move
+                    // that exact Role owner through the durable cleanup lane before a
+                    // later retry creates the successor generation.
+                    this.#requireCleanup(request.owner);
+                }
+                throw new RuntimeLaunchError(true, launchId, error.message, error instanceof RuntimeHostContentionError
+                    ? error.reason
+                    : "previous-process");
+            }
             if (error instanceof RuntimeBindingContractError) {
                 // Never pass an untrusted hostRef to stop(). Reconcile the requested
                 // owner through the durable, owner-addressed cleanup lane instead.
@@ -259,17 +317,15 @@ export class RuntimeLaunchCoordinator {
         catch (error) {
             await this.#compensateStartedHost(request.owner, binding, launchId, runtimeIsolation, error);
         }
-        if (request.owner.scope === "task"
-            && request.adapterId === "codex"
-            && request.runId !== undefined
+        if (launchCarriesExactRunPrompt
             && binding.hostCreated !== false
             && reservationConfirmation !== "provider-bound"
             && binding.initialPromptRunId !== request.runId) {
-            // Fresh Codex has no pre-input Provider event. It may return before its
-            // matching lifecycle Hook, but only an exact launch-carried Run marker
-            // can bridge that asynchronous interval. This is transport evidence,
-            // never Provider acceptance; the reservation remains fenced until the
-            // matching Hook binds the native Session.
+            // A launch-carried prompt may return before its matching lifecycle Hook,
+            // but only an exact Run marker can bridge that asynchronous interval.
+            // This is transport evidence, never Provider acceptance; the
+            // reservation remains fenced until the matching Hook binds the native
+            // Session.
             this.#requireCleanup(request.owner);
             throw new RuntimeBindingContractError(`Session host cannot acknowledge the exact launch-carried prompt: ${request.owner.roleName}.`);
         }
@@ -342,7 +398,8 @@ export class RuntimeLaunchCoordinator {
             }, this.#now())) {
             this.#requireCleanup(owner);
         }
-        throw cause;
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new RuntimeLaunchStateChangedError(`Runtime launch was compensated after state changed: ${detail}`, { cause });
     }
     #preflightRuntimeIsolation(request, launchId, generationId, allowExactActive) {
         if (this.#runtimeIsolation === undefined || request.owner.scope !== "task") {
@@ -426,11 +483,6 @@ function requireMatchingRuntimeBinding(raw, request, launchId, launchPromptAckno
         && binding.initialPromptRunId !== request.runId) {
         throw new RuntimeBindingContractError(`Session host returned a launch-carried prompt for another Run: ${request.owner.roleName}.`);
     }
-    if (launchPromptAcknowledgementRequired
-        && binding.initialPromptRunId !== request.runId
-        && !(launchPromptUncertaintyAllowed && binding.hostCreated === false)) {
-        throw new RuntimeBindingContractError(`Session host cannot acknowledge the exact launch-carried prompt: ${request.owner.roleName}.`);
-    }
     if (binding.launchId !== launchId
         || !ownerMatches
         || binding.agentId !== request.agentId
@@ -439,13 +491,20 @@ function requireMatchingRuntimeBinding(raw, request, launchId, launchPromptAckno
             && binding.nativeSessionId !== request.nativeSessionId)) {
         throw new RuntimeBindingContractError(`Session host returned a binding that does not match the requested runtime: ${request.owner.roleName}.`);
     }
+    if (launchPromptAcknowledgementRequired
+        && binding.initialPromptRunId !== request.runId
+        && !(launchPromptUncertaintyAllowed && binding.hostCreated === false)) {
+        throw binding.hostCreated === false
+            ? new LaunchSubmittedHostBusyError(`An earlier managed runtime is still exiting: ${request.owner.roleName}.`)
+            : new RuntimeBindingContractError(`Session host cannot acknowledge the exact launch-carried prompt: ${request.owner.roleName}.`);
+    }
     if (launchPromptAcknowledgementRequired
         && launchPromptUncertaintyAllowed
         && binding.hostCreated === false
         && request.runId !== undefined
         && binding.initialPromptRunId !== request.runId) {
         // A Controller restart can lose only the in-memory fact that a still-
-        // running Codex generation carried this Run in its launch argv. Keep the
+        // running generation carried this Run at process launch. Keep the
         // uncertainty explicitly tied to the exact reservation/Run; the matching
         // Provider Hook remains the sole acceptance authority.
         return {
@@ -455,6 +514,12 @@ function requireMatchingRuntimeBinding(raw, request, launchId, launchPromptAckno
     }
     return binding;
 }
+function carriesExactRunPrompt(request) {
+    if (request.owner.scope !== "task" || request.runId === undefined)
+        return false;
+    return request.adapterId === "claude"
+        || (request.adapterId === "codex" && request.mode === "new");
+}
 function defaultLaunchFingerprint(request) {
     return createHash("sha256").update(JSON.stringify([
         request.owner,

package/dist/controller/runtimeObservationHook.js

@@ -0,0 +1,112 @@
+import { callController } from "../core/controllerClient.js";
+import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
+import { normalizeAgentDriverHookClassification } from "../runtime/agentDriver.js";
+import { mapAgentDriverHook } from "../runtime/agentDriverObservation.js";
+import { runtimeLifecycleSignalKey } from "../runtime/lifecycleReservation.js";
+import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
+import { FileRuntimeEventInbox, MAX_RUNTIME_EVENT_FILE_BYTES } from "./runtimeEventInbox.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/Run fence.
+ */
+export async function runRuntimeObservationHookCommand(stdinJson, environment = process.env, call = callController, now = new Date(), dependencies = {}) {
+    const parsed = parseRuntimeObservationHook(stdinJson, environment, now, dependencies);
+    const inbox = new FileRuntimeEventInbox(parsed.home);
+    for (const observation of parsed.observations)
+        inbox.enqueueObservation(observation);
+    // The immutable inbox write is authoritative. The socket call only reduces
+    // observation latency when the Controller is currently available.
+    await call(parsed.home, "scheduler.signal", {
+        key: runtimeLifecycleSignalKey({
+            scope: "task",
+            taskId: parsed.taskId,
+            roleName: parsed.roleName
+        })
+    }, { timeoutMs: 100 }).catch(() => { });
+}
+export function parseRuntimeObservationHook(stdinJson, environment, now = new Date(), dependencies = {}) {
+    const payload = parseObject(stdinJson);
+    const drivers = dependencies.drivers ?? builtinAgentDriverRegistry();
+    const driverId = requireIdentity(environment.YUI_DRIVER_ID, "Agent Driver id");
+    const driver = drivers.require(driverId);
+    const hookEventName = requireIdentity(payload.hook_event_name, "Agent Driver Hook event name");
+    const receivedAt = now.toISOString();
+    const sequence = (dependencies.sequence ?? monotonicSequence)();
+    const occurrenceId = `${receivedAt}:${sequence}`;
+    const nativeHook = Object.freeze({ hookEventName, payload, occurrenceId });
+    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.resolveRunFence ?? resolveRuntimeHookRunFence)(environment, driver.adapterId, nativeSessionId, {
+        ...(classification.startupSession === undefined
+            ? {}
+            : { startupSession: classification.startupSession }),
+        terminal: classification.terminal,
+        ...(nativeTurnId === undefined ? {} : { nativeTurnId })
+    });
+    const driverInput = {
+        driver,
+        hookEventName,
+        receivedAt,
+        // Hook commands run in separate short-lived processes. CLOCK_MONOTONIC is
+        // shared by those processes on the host, so this preserves their order
+        // when wall-clock timestamps land in the same millisecond.
+        sequence,
+        occurrenceId,
+        fence: {
+            taskId: fence.taskId,
+            roleName: fence.roleName,
+            runId: fence.runId,
+            agentId: fence.agentId,
+            driverId,
+            launchId: fence.launchId,
+            sessionGenerationId: fence.launchId,
+            nativeSessionId: fence.nativeSessionId,
+            nativeTurnId: nativeTurnId ?? fence.runId,
+            receiptId: fence.receiptId ?? formatAgentRunReceiptId(fence.taskId, fence.runId)
+        },
+        payload
+    };
+    const observations = [mapAgentDriverHook({ ...driverInput, ordinal: 0 })];
+    return {
+        home: requireIdentity(environment.YUI_HOME, "YUI_HOME"),
+        taskId: fence.taskId,
+        roleName: fence.roleName,
+        observations: Object.freeze(observations)
+    };
+}
+function monotonicSequence() {
+    return Number(process.hrtime.bigint() / 1000n);
+}
+function parseObject(value) {
+    if (value === undefined
+        || Buffer.byteLength(value, "utf8") > MAX_RUNTIME_EVENT_FILE_BYTES) {
+        throw new Error("Agent Driver lifecycle Hook stdin JSON is invalid.");
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            throw new Error("shape");
+        return parsed;
+    }
+    catch {
+        throw new Error("Agent Driver lifecycle Hook stdin JSON is invalid.");
+    }
+}
+function optionalIdentity(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    return requireIdentity(value, "Agent Driver native Turn id");
+}
+function requireIdentity(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is required.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0 || normalized.length > 1_024) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}

package/dist/core/controllerServer.js

@@ -732,6 +732,11 @@ function safeDispatcherError(error) {
                 }
                 return { code: "SERVICE_ERROR", message };
             }
+            case "RuntimeLaunchStateChangedError":
+                // The launch coordinator already stopped the exact host and bounded
+                // the detail to its currentness/reservation contract. Surface that
+                // actionable diagnosis instead of collapsing it to INTERNAL_ERROR.
+                return { code: "SERVICE_ERROR", message };
             default:
                 return undefined;
         }

package/dist/executor/agentAdapter.js

@@ -6,7 +6,7 @@ import { ownedArgumentsForAdapter, validateAgentAdvancedArguments, validateAgent
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { inspectCodexDeveloperInstructions } from "./codexConfigConflict.js";
 import { discoverClaudeConfiguration, discoverCodexConfiguration } from "./agentConfigurationProbe.js";
-import { preInputReadinessCapability } from "../lifecycle/providerLifecycleMapping.js";
+import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 const SANDBOXES = ["read-only", "workspace-write", "danger-full-access"];
 const APPROVALS = ["untrusted", "on-request", "never"];
 const PROBE_TIMEOUT_MS = 2_000;
@@ -57,7 +57,7 @@ class CodexAdapter extends BaseAdapter {
         recover: true,
         interrupt: true,
         nativeSessionDiscovery: "runtime",
-        preInputReadiness: preInputReadinessCapability("codex")
+        preInputReadiness: driverPreInputReadiness("codex")
     };
     discoverConfiguration(input) {
         return discoverCodexConfiguration(input);
@@ -166,7 +166,7 @@ class ClaudeAdapter extends BaseAdapter {
         recover: true,
         interrupt: true,
         nativeSessionDiscovery: "preallocated",
-        preInputReadiness: preInputReadinessCapability("claude")
+        preInputReadiness: driverPreInputReadiness("claude")
     };
     discoverConfiguration(input) {
         return discoverClaudeConfiguration(input);
@@ -257,6 +257,21 @@ class ClaudeAdapter extends BaseAdapter {
         return { ...launch, argv: [...launch.argv, "--resume", nativeId(input.nativeSessionId)] };
     }
 }
+function driverPreInputReadiness(adapterId) {
+    const capability = builtinAgentDriverRegistry().requireByAdapterId(adapterId)
+        .capabilities.observation.preInputReadiness;
+    return capability === "exact"
+        ? Object.freeze({
+            status: "supported",
+            nativeEvent: "Agent Driver session.ready",
+            note: "The registered Agent Driver supplies an exact pre-input readiness observation."
+        })
+        : Object.freeze({
+            status: "unsupported",
+            reason: "not-available",
+            note: "The registered Agent Driver does not expose exact pre-input readiness."
+        });
+}
 const ADAPTERS = {
     codex: new CodexAdapter(), claude: new ClaudeAdapter()
 };