@zq-silk/yui 0.15.9 → 0.15.12

package/dist/controller/runtime.js

@@ -1,5 +1,4 @@
 import { reconciliationIntervalMilliseconds, resolveAgentLaunchInactivityTimeoutSeconds, resolveControllerTaskConcurrency, resolveDeliveryTimeoutSeconds, resolveRuntimeHealth, resolveTmuxBin, resolveTmuxHistoryLimit } from "../config/yuiConfig.js";
-import { resolve } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { controllerSocketPath } from "../core/controllerEndpoint.js";
 import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, NATIVE_AGENT_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES } from "../agent/launchEnvironment.js";
@@ -11,6 +10,7 @@ import { AgentConfigurationCatalogService, validateAgentLaunchConfiguration } fr
 import { isTaskOwnedWorkspace, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { FileRoleLaunchPlanner } from "../executor/fileRoleLaunchPlanner.js";
 import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
+import { managedRuntimeRoot } from "../storage/homeLayout.js";
 import { SqliteTaskStore } from "../storage/sqliteStore.js";
 import { AsyncTaskStoreClient, resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
 import { FileTaskWorkspacePreparer } from "../repository/taskWorkspacePreparer.js";
@@ -41,9 +41,14 @@ import { createResourceAutoGc } from "../resources/autoResourceGc.js";
 import { createRuntimeResourceActivityTracker } from "./resourceInventory.js";
 import { SessionOwnerReconciliation } from "./sessionOwnerReconciliation.js";
 import { launchBrokerForHome } from "../runtime/launchBroker.js";
+import { assertExecutionEnvironmentCurrent } from "../runtime/executionEnvironment.js";
 import { classifyRuntimeProcessExit, validateRuntimeProcessExitObservation } from "../runtime/processExitObservation.js";
 import { replayRuntimeProcessExitOutbox } from "../runtime/processExitOutbox.js";
 import { appendGlobalProcessExitObservation } from "../runtime/globalProcessExitStore.js";
+import { deliverGlobalInputs } from "./globalInputDelivery.js";
+import { providerRetryPrompt } from "../runtime/providerRetry.js";
+import { createProviderRetryHooks } from "./providerRetryDelivery.js";
+import { createGlobalRoleMessage } from "../message/message.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
 import { createRuntimeObservation, runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
 import { createTaskEvent } from "../event/taskEvent.js";
@@ -174,11 +179,14 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             ?? new AgentHostPromptPushAdapter(home);
         const runtimeIsolation = options.runtimeIsolation
             ?? new FileTaskRuntimeIsolation({
-                // A sibling of the exact control Home keeps provider data/cache/tmp out
-                // of both the shared control plane and every managed Git workspace.
-                runtimeRoot: `${resolve(home)}.task-runtimes`,
+                // Provider data/cache/tmp live in a dedicated Home partition. The
+                // control boundary permits runtime roots to overlap only this exact
+                // subtree, keeping them out of the database, managed Git workspaces and
+                // every other part of the control plane.
+                runtimeRoot: managedRuntimeRoot(home),
                 controlPlane: {
                     yuiHome: home,
+                    managedRuntimeRoot: managedRuntimeRoot(home),
                     controllerSocketPath: controllerSocketPath(homeId),
                     tmuxNamespace: yuiTmuxServerName(home),
                     globalInstallPaths: [process.execPath]
@@ -239,6 +247,31 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             sessionHost,
             promptPush,
             launchCoordinator,
+            notifyOperatorInputOnce: async (input) => {
+                // The original attention mailbox remains pending until this one
+                // Global Message has an actual Provider receipt. Never inject keys
+                // into a busy Host console and mistake that for accepted attention.
+                const message = store.transaction(tx => {
+                    const requestId = `operator-notice:${encodeURIComponent(input.receiptId)}`;
+                    const previous = tx.listGlobalRoleMessages("operator").find(entry => (entry.inputControl ?? entry.interruptThen?.reusedInput)?.requestId === requestId);
+                    if (previous !== undefined)
+                        return previous;
+                    const sessions = tx.getGlobalRoleSessionSet("operator");
+                    const session = sessions?.sessions[sessions.activeAgentId];
+                    if (session?.status !== "active" || sessions?.providerBinding == null)
+                        return null;
+                    const created = { ...createGlobalRoleMessage(tx.nextGlobalRoleMessageId(), "operator", input.text, "system", { type: "system" }, new Date(), { inputControl: { action: "queue", requestId } }),
+                        deliveryTarget: { agentId: session.agentId, nativeSessionId: session.nativeSessionId } };
+                    tx.saveGlobalRoleMessage(created);
+                    return created;
+                });
+                if (message === null)
+                    return "unavailable";
+                if (message.delivery?.via === "provider")
+                    return "already-sent";
+                runningRuntime?.signal("global-role:operator");
+                return "not-ready";
+            },
             roleResourceInventory: async (panes, inputs) => {
                 const inventory = await scanInventory(panes);
                 return inventory.resources.flatMap((resource) => {
@@ -439,7 +472,30 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             now: options.now,
             onError: options.onError,
             lifecycleHost,
+            providerRetry: createProviderRetryHooks(home, store, {
+                now: options.now,
+                onError: options.onError,
+                snapshotTaskCandidate: async (run) => {
+                    if (run.purpose !== "review" || run.reviewRoundId === undefined)
+                        return undefined;
+                    const round = store.getReviewRound(run.taskId, run.reviewRoundId);
+                    if (round?.scope !== "task")
+                        return undefined;
+                    const task = store.getTask(run.taskId);
+                    const workspace = store.getTaskWorkspace(run.taskId);
+                    if (task === null || workspace === null || !(workspacePreparer instanceof FileTaskWorkspacePreparer)) {
+                        throw new Error("Task-final retry requires an observable authoritative Task workspace.");
+                    }
+                    const snapshot = await workspacePreparer.snapshotDirectTaskMain(workspace, task.projectBindings.map(p => p.projectId));
+                    return { schemaVersion: 1, projects: snapshot.projects.map(p => ({
+                            projectId: p.projectId, commit: p.headCommit
+                        })) };
+                }
+            }),
             jobSupervisor,
+            globalInputDelivery: () => deliverGlobalInputs(home, store, async (roleName) => {
+                await lifecycleDispatcher("runtime.ensure-role-session", { scope: "global", roleName });
+            }, options.onError ?? (() => undefined)),
             jobControl,
             capabilityDispatcher: createCapabilityDispatcher(kernel.capabilities),
             ...(continuationReconciler === undefined ? {} : { continuationReconciler }),
@@ -546,6 +602,20 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
         });
     const lifecycleTails = new Map();
     return async (method, params) => {
+        if (method === "runtime.host-observation-apply") {
+            const id = params.eventId;
+            if (typeof id !== "string")
+                throw applicationError("INVALID_PARAMS", "Host event id is required.");
+            // Eager delivery is only a hint about the exact immutable Inbox file.
+            // Missing means the normal drainer has already committed and ACKed it.
+            const event = new FileRuntimeEventInbox(store.rootDirectory()).read(id);
+            if (event === null)
+                return { outcome: "applied" };
+            if (event.type !== "runtime-observation" || event.host === undefined) {
+                throw applicationError("INVALID_PARAMS", "Expected an Agent Host observation.");
+            }
+            return { outcome: schedulerStore.observeAgentHostObservation(event, new Date()) };
+        }
         if (method === "runtime.observation-apply") {
             try {
                 return {
@@ -569,6 +639,8 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
                     authorityEpoch: value.authorityEpoch,
                     authorityOwner: value.authorityOwner,
                     holderId: value.holderId,
+                    boundedText: value.boundedText,
+                    retrySupported: value.retrySupported,
                     now: value.now
                 });
             }
@@ -580,7 +652,15 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
                 }
                 throw error;
             }
-            return { recorded: true };
+            const binding = (value.taskId === undefined
+                ? store.getGlobalRoleSessionSet(value.roleName)
+                : store.getTaskRoleSessionSet(value.taskId, value.roleName))?.providerBinding;
+            const retry = binding?.retry;
+            return { recorded: true, ...(retry?.currentAttemptId === value.attemptId && value.boundedText !== undefined
+                    ? { retryInput: {
+                            text: providerRetryPrompt(retry, value.boundedText),
+                            ...(retry.failedNativeTurnId === undefined ? {} : { expectedFailedNativeTurnId: retry.failedNativeTurnId })
+                        } } : {}) };
         }
         if (method === "runtime.provider-turn-submission-resolve") {
             const value = providerTurnControlParams(params);
@@ -600,6 +680,7 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
                 status,
                 reason,
                 raw,
+                noProviderWrite: params.providerWrite === "not-issued",
                 now: value.now
             });
             return { recorded: true };
@@ -676,7 +757,34 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
             }
             // The launch payload is validated at reservation time and every member
             // of its discriminated Provider-control union is JSON serializable.
-            return launchBrokerForHome(store.rootDirectory()).redeem(ticket);
+            const payload = launchBrokerForHome(store.rootDirectory()).redeem(ticket);
+            if (payload.executionEnvironment !== undefined) {
+                if (payload.environment.YUI_SESSION_SCOPE !== "task"
+                    || payload.environment.YUI_TASK_ID !== payload.executionEnvironment.taskId
+                    || payload.cwd !== payload.executionEnvironment.directory.path) {
+                    throw applicationError("INVALID_PARAMS", "Launch does not match its adopted execution environment.");
+                }
+                assertExecutionEnvironmentCurrent(store, payload.executionEnvironment.taskId, payload.executionEnvironment);
+            }
+            return payload;
+        }
+        if (method === "runtime.execution-environment-check") {
+            const value = params;
+            const { taskId, roleName, agentId, nativeSessionId, workspace } = value;
+            if ([taskId, roleName, agentId, nativeSessionId, workspace].some(v => typeof v !== "string")) {
+                throw applicationError("INVALID_PARAMS", "Exact Host execution identity is required.");
+            }
+            const sessions = store.getTaskRoleSessionSet(taskId, roleName);
+            const session = sessions?.sessions[agentId];
+            if (sessions?.activeAgentId !== agentId || session?.status !== "active"
+                || session.nativeSessionId !== nativeSessionId
+                || (session.effective.executionEnvironment?.directory.path ?? session.effective.workspace.root) !== workspace) {
+                throw applicationError("INVALID_PARAMS", "Host no longer owns the current execution environment.");
+            }
+            if (session.effective.executionEnvironment !== undefined) {
+                assertExecutionEnvironmentCurrent(store, taskId, session.effective.executionEnvironment);
+            }
+            return { current: true };
         }
         if (method === "runtime.replace-agent-environment") {
             if (environmentRefresher === undefined) {
@@ -1123,7 +1231,7 @@ function providerTurnControlParams(params) {
         throw applicationError("INVALID_PARAMS", "Provider Turn control fence is invalid.");
     }
     return {
-        taskId: requiredParam(value.taskId),
+        ...(value.taskId === undefined ? {} : { taskId: requiredParam(value.taskId) }),
         roleName: requiredParam(value.roleName),
         ...(value.runId === undefined ? {} : { runId: requiredParam(value.runId) }),
         agentId: requiredParam(value.agentId),
@@ -1132,6 +1240,8 @@ function providerTurnControlParams(params) {
         authorityEpoch: authorityEpoch,
         authorityOwner,
         holderId: requiredParam(value.holderId),
+        ...(value.boundedText === undefined ? {} : { boundedText: requiredParam(value.boundedText) }),
+        ...(value.retrySupport === undefined ? {} : { retrySupported: value.retrySupport === "codex-failed-turn-v1" }),
         now: new Date(observedAt)
     };
 }

package/dist/controller/runtimeEventInbox.js

@@ -4,6 +4,7 @@ import { closeSync, constants, existsSync, fchmodSync, fsyncSync, linkSync, lsta
 import { join } from "node:path";
 import { createRuntimeObservation, isRuntimeTokenEvidence } from "../runtime/runtimeObservation.js";
 import { boundedRunFailureDiagnostic, transportAgentResult } from "../domain/agentResultTransport.js";
+import { readAgentHostObservationSource } from "../runtime/agentHostProtocol.js";
 export const MAX_RUNTIME_EVENT_FILE_BYTES = 16 * 1024 * 1024;
 const RUNTIME_EVENT_DIRECTORY = join("runtime", "inbox");
 const INVALID_RUNTIME_EVENT_DIRECTORY = join("runtime", "inbox-invalid");
@@ -24,7 +25,7 @@ export class FileRuntimeEventInbox {
         this.hooks = hooks;
         this.directory = join(home, RUNTIME_EVENT_DIRECTORY);
     }
-    enqueueObservation(input) {
+    enqueueObservation(input, host) {
         const observation = createRuntimeObservation(input);
         const scope = observation.fence.taskId === undefined ? "global" : "task";
         const event = Object.freeze({
@@ -36,7 +37,8 @@ export class FileRuntimeEventInbox {
             ...(observation.fence.taskId === undefined
                 ? {}
                 : { taskId: observation.fence.taskId }),
-            observation
+            observation,
+            ...(host === undefined ? {} : { host: readAgentHostObservationSource(host) })
         });
         return this.publish(event);
     }
@@ -117,6 +119,20 @@ export class FileRuntimeEventInbox {
         }
         return event;
     }
+    /** Producer-local delivery diagnostics need only existence, never a read of
+     * another version's payload or permission to quarantine another producer. */
+    has(id) {
+        assertEventId(id);
+        try {
+            lstatSync(this.eventPath(id));
+            return true;
+        }
+        catch (error) {
+            if (isNodeError(error, "ENOENT"))
+                return false;
+            throw error;
+        }
+    }
     acknowledge(id) {
         assertEventId(id);
         try {
@@ -408,6 +424,7 @@ function parseRuntimeEvent(value) {
 function parseRuntimeObservationEvent(value) {
     const expected = [
         "schemaVersion", "id", "type", "receivedAt", "scope", "observation",
+        ...(value.host === undefined ? [] : ["host"]),
         ...(value.taskId === undefined ? [] : ["taskId"])
     ];
     if (value.schemaVersion !== 1 || !hasExactKeys(value, expected))
@@ -426,9 +443,18 @@ function parseRuntimeObservationEvent(value) {
         receivedAt: observation.receivedAt,
         scope,
         ...(scope === "task" ? { taskId: observation.fence.taskId } : {}),
-        observation
+        observation,
+        ...(value.host === undefined ? {} : { host: parseHostSource(value.host) })
     });
 }
+function parseHostSource(value) {
+    try {
+        return readAgentHostObservationSource(value);
+    }
+    catch (error) {
+        throw invalidEvent(error instanceof Error ? error.message : String(error));
+    }
+}
 function parseDurableJobTerminalEvent(value) {
     const expected = [
         "schemaVersion", "id", "type", "receivedAt", "scope", "taskId",
@@ -520,6 +546,9 @@ function assertEventId(id) {
         throw invalidEvent("Runtime event id is invalid.");
 }
 function hasSameIdentity(left, right) {
+    if (left.type === "runtime-observation" && right.type === "runtime-observation"
+        && !isDeepStrictEqual(left.host, right.host))
+        return false;
     if (left.type === "runtime-observation" && right.type === "runtime-observation"
         && ["turn.completed", "turn.failed", "turn.cancelled"].includes(left.observation.kind)) {
         return left.id === right.id

package/dist/controller/runtimeEventProcessor.js

@@ -143,11 +143,17 @@ export class FileRuntimeEventProcessor {
         return { candidate, outcome };
     }
     applyRuntimeObservation(event, now) {
+        if (event.host !== undefined) {
+            return this.observer.observeAgentHostObservation?.(event, now) ?? "deferred";
+        }
         const taskId = event.observation.fence.taskId;
         if (taskId !== undefined) {
             const task = this.observer.getTask(taskId);
+            if (task?.status === "archived") {
+                this.recordObsolete(event, "task-archived", now);
+                return "obsolete";
+            }
             if (task === null
-                || task.status === "archived"
                 || (!["turn.completed", "turn.failed", "turn.cancelled"].includes(event.observation.kind)
                     && (task.status !== "active" || task.executionGate.state !== "enabled")))
                 return "obsolete";
@@ -247,7 +253,8 @@ export class FileRuntimeEventProcessor {
                 agentId: fence.agentId,
                 ...(fence.runId === undefined ? {} : { runId: fence.runId }),
                 nativeSessionId: fence.nativeSessionId,
-                reason
+                reason,
+                ...(reason === "task-archived" ? { originalEvent: event } : {})
             }, now);
             return;
         }
@@ -263,7 +270,8 @@ export class FileRuntimeEventProcessor {
             agentId: event.agentId,
             ...(event.runId === undefined ? {} : { runId: event.runId }),
             nativeSessionId: event.nativeSessionId,
-            reason
+            reason,
+            ...(reason === "task-archived" ? { originalEvent: event } : {})
         }, now);
     }
     acknowledge(ids, acknowledged) {
@@ -394,6 +402,9 @@ function progressStreamKey(event) {
         fence.driverId,
         fence.nativeSessionId ?? null,
         fence.runId ?? null,
+        fence.receiptId ?? null,
+        fence.nativeTurnId ?? null,
+        event.host ?? null,
         payload.activity,
         isRuntimeTokenEvidence(event.observation) ? "usage" : "signal"
     ]);
@@ -510,6 +521,7 @@ export function createAsyncRuntimeObserver(invoke) {
     const withNow = (method, input, now) => now === undefined ? call(method, [input]) : call(method, [input, now]);
     return {
         getTask: (taskId) => call("getTask", [taskId]),
+        observeAgentHostObservation: (input, now) => withNow("observeAgentHostObservation", input, now),
         observeRuntimeObservation: (input, now) => withNow("observeRuntimeObservation", input, now),
         observeRuntimeRunTerminal: (input, now) => withNow("observeRuntimeRunTerminal", input, now),
         observeGlobalRuntimeRunTerminal: (input, now) => withNow("observeGlobalRuntimeRunTerminal", input, now),
@@ -605,11 +617,17 @@ export class AsyncRuntimeEventProcessor {
         };
     }
     async applyRuntimeObservation(event, now) {
+        if (event.host !== undefined) {
+            return this.observer.observeAgentHostObservation?.(event, now) ?? "deferred";
+        }
         const taskId = event.observation.fence.taskId;
         if (taskId !== undefined) {
             const task = await this.observer.getTask(taskId);
+            if (task?.status === "archived") {
+                await this.recordObsolete(event, "task-archived", now);
+                return "obsolete";
+            }
             if (task === null
-                || task.status === "archived"
                 || (!["turn.completed", "turn.failed", "turn.cancelled"].includes(event.observation.kind)
                     && (task.status !== "active" || task.executionGate.state !== "enabled")))
                 return "obsolete";
@@ -685,7 +703,8 @@ export class AsyncRuntimeEventProcessor {
                 agentId: fence.agentId,
                 ...(fence.runId === undefined ? {} : { runId: fence.runId }),
                 nativeSessionId: fence.nativeSessionId,
-                reason
+                reason,
+                ...(reason === "task-archived" ? { originalEvent: event } : {})
             }, now);
             return;
         }
@@ -697,7 +716,8 @@ export class AsyncRuntimeEventProcessor {
             agentId: event.agentId,
             ...(event.runId === undefined ? {} : { runId: event.runId }),
             nativeSessionId: event.nativeSessionId,
-            reason
+            reason,
+            ...(reason === "task-archived" ? { originalEvent: event } : {})
         }, now);
     }
     acknowledge(ids, acknowledged) {

package/dist/controller/runtimeHookRunFence.js

@@ -5,27 +5,66 @@ import { formatRunReceiptId } from "../task/taskRecordReference.js";
 import { currentProviderConversation, managedProviderTurnId } from "../runtime/providerRuntimeIdentity.js";
 import { taskRoleRuntimeIdentity } from "../runtime/managedCaller.js";
 import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
+export class RuntimeHookRunFenceError extends Error {
+}
 /**
  * Resolve observations by Session and exact input identity. A startup Hook
  * may introduce a Session for an explicit new-Session AgentRun.
  */
-export function resolveRuntimeHookRunFence(environment, adapterId, payloadNativeSessionId, options = {}) {
+export function resolveRuntimeHookRunFence(environment, adapterId, payloadNativeSessionId, options = {}, currentStore) {
+    if (currentStore === undefined) {
+        const store = openCurrentTaskStore(requireIdentity(environment.YUI_HOME, "YUI_HOME"));
+        try {
+            return resolveRuntimeHookRunFence(environment, adapterId, payloadNativeSessionId, options, store);
+        }
+        finally {
+            store.close();
+        }
+    }
+    if (environment.YUI_SESSION_SCOPE === "global") {
+        if (environment.YUI_ADAPTER_ID !== adapterId)
+            throw new RuntimeHookRunFenceError("Global observation adapter mismatch.");
+        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 nativeSessionId = requireIdentity(payloadNativeSessionId, "Provider session id");
+        const sessions = currentStore.getGlobalRoleSessionSet(roleName);
+        const role = currentStore.getGlobalRole(roleName);
+        const session = sessions?.sessions[agentId];
+        const turn = sessions?.providerBinding?.run;
+        if (role?.activeAgentId !== agentId || sessions?.activeAgentId !== agentId || session?.adapterId !== adapterId
+            || session.status === "ended"
+            || session.nativeSessionId !== nativeSessionId || session.effective.workspace.root !== workspace) {
+            throw new RuntimeHookRunFenceError("Global observation Session does not match durable state.");
+        }
+        if (options.attemptId !== undefined && turn?.attemptId !== options.attemptId
+            || options.nativeTurnId !== undefined && turn?.nativeTurnId !== undefined
+                && turn.nativeTurnId !== options.nativeTurnId) {
+            throw new RuntimeHookRunFenceError("Global observation does not match the exact current input.");
+        }
+        if (options.exactInput && (turn == null
+            || options.attemptId === undefined && (options.nativeTurnId === undefined || turn.nativeTurnId !== options.nativeTurnId)
+            || ["rejected", "deferred"].includes(turn.status))) {
+            throw new RuntimeHookRunFenceError("Global observation input has no exact execution binding.");
+        }
+        return { roleName, agentId, workspace, nativeSessionId,
+            ...(options.sessionOnly || turn == null ? {} : { receiptId: turn.attemptId }) };
+    }
     if (environment.YUI_SESSION_SCOPE !== "task") {
-        throw new Error("Runtime observation Hook requires a Task session scope.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook requires a Task session scope.");
     }
     if (environment.YUI_ADAPTER_ID !== adapterId) {
-        throw new Error(`Runtime observation Hook requires the ${adapterId} adapter.`);
+        throw new RuntimeHookRunFenceError(`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 nativeSessionId = requireIdentity(payloadNativeSessionId, "Provider session id");
-    const store = openCurrentTaskStore(home);
+    const store = currentStore;
     const task = store.getTask(taskId);
     if (task === null) {
-        throw new Error("Runtime observation Hook Task does not accept this lifecycle boundary.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook Task does not accept this lifecycle boundary.");
     }
     const role = store.getRole(taskId, roleName);
     const sessions = store.getTaskRoleSessionSet(taskId, roleName);
@@ -56,6 +95,14 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
         taskId, roleName, agentId, nativeSessionId,
         continuationId: options.continuationId,
     }));
+    if (options.exactInput && acceptedBinding === null && !matchesProviderTurn) {
+        throw new RuntimeHookRunFenceError("Runtime observation Hook input has no exact accepted execution binding.");
+    }
+    if (options.startupRunId !== undefined && options.startupRunId !== activeRun?.id) {
+        // A historical Session can report terminal evidence, but its old startup
+        // must not bind a new Session under a successor's active Run.
+        throw new RuntimeHookRunFenceError("Runtime observation Hook startup does not match its exact launch Run.");
+    }
     // Collection of an exactly accepted terminal fact is not a new action by
     // the Role. A successor's active Agent or revoked execution permission
     // cannot erase the original AgentRun's evidence.
@@ -70,17 +117,26 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
         && activeRun.purpose === "planning"
         && activeRun.roleName === roleName
         && runPurposeAdmitsTaskState(activeRun.purpose, task);
+    // Restoring the Draft Leader's existing planning Session needs no new Run.
+    // Admit its Session facts; the shared identity/workspace fence below still
+    // requires the exact current Session and never grants delivery authority.
+    const planningSessionObservation = options.sessionOnly === true
+        && task.status === "draft" && roleName === "leader"
+        && runPurposeAdmitsTaskState("planning", task)
+        && session?.status === "active"
+        && session.effective.executionAuthority === "planning";
     if (!(task.status === "active" && task.executionGate.state === "enabled")
         && !(task.status === "completed" && options.sessionOnly === true)
         && !planningObservation
+        && !planningSessionObservation
         && !existingExecutionObservation) {
-        throw new Error("Runtime observation Hook Task does not accept this lifecycle boundary.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook Task does not accept this lifecycle boundary.");
     }
     const runtimeIdentity = role === null ? null : taskRoleRuntimeIdentity(role, activeRun);
     if (!existingExecutionObservation && (runtimeIdentity === null || runtimeIdentity.agentId !== agentId
         || runtimeIdentity.adapterId !== adapterId
         || (sessions !== null && sessions.activeAgentId !== agentId))) {
-        throw new Error("Runtime observation Hook Role or Agent is not current.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook Role or Agent is not current.");
     }
     const lifecycleMailbox = store.getWorkMailbox(runtimeLifecycleTarget({
         scope: "task",
@@ -97,7 +153,7 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
             || observedSession.adapterId !== adapterId
             || observedSession.nativeSessionId !== nativeSessionId
             || observedSession.effective.workspace.root !== workspace) {
-            throw new Error("Runtime observation Hook Session does not match durable state.");
+            throw new RuntimeHookRunFenceError("Runtime observation Hook Session does not match durable state.");
         }
         return {
             taskId,
@@ -146,7 +202,7 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
         ? managedProviderTurnId(providerTurn) ?? undefined
         : undefined;
     if (options.terminal === true && acceptedBinding === null && registeredRunId === undefined) {
-        throw new Error("Runtime observation Hook terminal has no exact accepted execution binding.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook terminal has no exact accepted execution binding.");
     }
     const terminalRun = acceptedBinding !== null
         ? store.getRun(taskId, acceptedBinding.fence.runId)
@@ -166,7 +222,7 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
         && !exactTerminal
         && registeredRunId === undefined
         && acceptedBinding === null) {
-        throw new Error("Runtime observation Hook has no matching durable in-flight AgentRun.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook has no matching durable in-flight AgentRun.");
     }
     const runId = acceptedBinding?.fence.runId
         ?? registeredRunId
@@ -181,21 +237,21 @@ export function resolveRuntimeHookRunFence(environment, adapterId, payloadNative
         || run.roleName !== roleName
         || run.effective.agentId !== agentId
         || run.effective.adapterId !== adapterId) {
-        throw new Error("Runtime observation Hook AgentRun does not match durable active state.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook AgentRun does not match durable active state.");
     }
     if (run.effective.workspace.root !== workspace) {
-        throw new Error("Runtime observation Hook workspace does not match the durable AgentRun snapshot.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook workspace does not match the durable AgentRun snapshot.");
     }
     if (session !== undefined && acceptedBinding === null && !matchesProviderTurn && !replacementStartup && !resumedStartup) {
         if (session.adapterId !== adapterId
             || session.nativeSessionId !== nativeSessionId
             || session.effective.workspace.root !== workspace) {
-            throw new Error("Runtime observation Hook Session does not match durable state.");
+            throw new RuntimeHookRunFenceError("Runtime observation Hook Session does not match durable state.");
         }
     }
     else if (acceptedBinding === null && !matchesProviderTurn && (session === undefined || replacementStartup)) {
         if (!discoveredStartup && !preallocatedStartup) {
-            throw new Error("Runtime observation Hook has no matching new-Session intent.");
+            throw new RuntimeHookRunFenceError("Runtime observation Hook has no matching new-Session intent.");
         }
     }
     return {
@@ -230,7 +286,7 @@ function knownContinuationBinding(events, expected) {
         return null;
     if (matches.some((candidate) => candidate.fence.runId !== binding.fence.runId
         || candidate.fence.receiptId !== binding.fence.receiptId)) {
-        throw new Error("Runtime observation Hook continuation has conflicting durable AgentRun bindings.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook continuation has conflicting durable AgentRun bindings.");
     }
     return binding;
 }
@@ -260,17 +316,17 @@ function acceptedRunBinding(events, expected) {
             && candidate.fence.nativeTurnId !== expected.nativeTurnId)
         || candidate.fence.runId !== binding.fence.runId
         || candidate.fence.receiptId !== binding.fence.receiptId))) {
-        throw new Error("Runtime observation Hook native Turn has conflicting durable AgentRun bindings.");
+        throw new RuntimeHookRunFenceError("Runtime observation Hook native Turn has conflicting durable AgentRun bindings.");
     }
     return binding;
 }
 function requireIdentity(value, label) {
     if (typeof value !== "string" || value.includes("\0")) {
-        throw new Error(`${label} is required.`);
+        throw new RuntimeHookRunFenceError(`${label} is required.`);
     }
     const normalized = value.trim();
     if (normalized.length === 0 || normalized.length > 1_024) {
-        throw new Error(`${label} is invalid.`);
+        throw new RuntimeHookRunFenceError(`${label} is invalid.`);
     }
     return normalized;
 }