@zq-silk/yui 0.15.7 → 0.15.8

package/dist/executor/fileRoleLaunchPlanner.js

@@ -1,9 +1,12 @@
-import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { mkdirSync, realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
+import { assertExecutionEnvironmentCurrent } from "../runtime/executionEnvironment.js";
+import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
+import { taskOwnsManagedWorkspace } from "../task/task.js";
 import { configuredAgentToDefinition, resolveAgentEnvironment } from "../agent/agent.js";
 import { NATIVE_AGENT_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, operationalAgentEnvironment, selectEnvironment } from "../agent/launchEnvironment.js";
 import { activeRoleAgentBinding } from "../role/role.js";
@@ -12,15 +15,15 @@ import { compileRoleSessionContext, roleSessionKind } from "../context/roleSessi
 import { materializeSessionBootstrap } from "../context/sessionBootstrapManifest.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
 import { resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
-import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
 import { classifyWorkspacePreflight, formatWorkspacePreflightError } from "./workspacePreflightClassification.js";
-import { activeLiveRoleAgentSession } from "./agentExecutor.js";
+import { activeLiveRoleAgentSession, taskRoleControlTarget } from "./agentExecutor.js";
 import { roleSessionMayContinue, effectiveRoleForLaunch, resolveEffectiveLaunch } from "./effectiveLaunch.js";
 import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
 import { ResourceRegistrar } from "../resources/resourceRegistrar.js";
 import { builtinAgentDriverRegistry, builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 import { managedRuntimeAdmission } from "../runtime/agentDriver.js";
-import { assertProviderConversationReplaceable, currentProviderActivation } from "../runtime/providerRuntimeIdentity.js";
+import { builtinAgentEndpointImplementation, validateAgentEndpointImplementation } from "../runtime/agentEndpointIdentity.js";
+import { assertProviderConversationReplaceable } from "../runtime/providerRuntimeIdentity.js";
 import { assertCodexLaunchOverridesAvailable, inspectCodexLaunchConfig } from "./codexConfigConflict.js";
 /** Builds managed native Agent launches from the authoritative Task records. */
 export class FileRoleLaunchPlanner {
@@ -64,42 +67,83 @@ export class FileRoleLaunchPlanner {
         this.#agentEnvironment = patchEnvironment(this.#agentEnvironment, refresh.sourceNames, refresh.sources);
         this.#nativeAgentEnvironment = patchEnvironment(this.#nativeAgentEnvironment, refresh.nativeNames, refresh.nativeSources);
     }
-    /**
-     * Commit the caller key for a task Session only after the runtime host has
-     * confirmed that it created a new native process.  An ensure/resume request
-     * that reuses a live host must keep the old durable hash because its process
-     * still carries the old plaintext key.
-     */
-    commitTaskCallerKey(input) {
-        const hash = createHash("sha256").update(input.callerKey).digest("hex");
-        this.store.setJobCallerKeyHash(input.taskId, input.roleName, input.agentId, hash);
+    /** Recovery addresses the recorded Agent/Session, independent of delivery
+     * admission, a missing worktree, or the old Endpoint code generation. */
+    planNativeControl(taskId, roleName) {
+        const set = this.store.getTaskRoleSessionSet(taskId, roleName);
+        const session = taskRoleControlTarget(set);
+        if (session?.adapterId !== "codex")
+            throw new Error("Native metadata control requires a recorded Codex Session.");
+        const configured = this.store.getConfiguredAgent(session.agentId);
+        if (configured === null || configured.adapterId !== session.adapterId) {
+            throw new Error("The recorded native Agent connection is unavailable.");
+        }
+        const agent = configuredAgentToDefinition(configured);
+        const connection = this.store.listEvents(taskId).find(event => event.type === "runtime.native-connection-bound"
+            && event.payload.roleName === roleName && event.payload.agentId === session.agentId
+            && event.payload.nativeSessionId === session.nativeSessionId)?.payload;
+        return {
+            command: configured.command, args: [...agent.baseArgs, "app-server", "proxy"], cwd: this.home,
+            expectedAccountHome: connection?.nativeAccountHome,
+            environment: {
+                ...operationalAgentEnvironment("codex", { ...this.#operationalEnvironment, ...this.#nativeAgentEnvironment }),
+                ...resolveAgentEnvironment(agent, this.#agentEnvironment),
+                ...(connection === undefined ? {} : { HOME: connection.home, CODEX_HOME: connection.codexHome })
+            }
+        };
     }
     plan(input) {
         const task = this.store.getTask(input.taskId);
         if (task === null)
             throw new Error(`Task not found: ${input.taskId}.`);
-        if (task.status !== "active" || task.executionGate.state !== "enabled") {
-            throw new Error(`Task execution is not enabled: ${input.taskId}.`);
-        }
         const role = this.store.getRole(input.taskId, input.roleName);
         if (role === null)
             throw new Error(`Role not found: ${input.taskId}/${input.roleName}.`);
-        const activeTurn = this.store.getActiveTurn(task.id, role.name);
-        if (input.turnId !== undefined && activeTurn?.id !== input.turnId) {
-            throw new Error(`Role Turn is no longer current: ${input.turnId}.`);
+        const activeRun = this.store.getActiveRun(task.id, role.name);
+        if (input.runId !== undefined && activeRun?.id !== input.runId) {
+            throw new Error(`Role AgentRun is no longer current: ${input.runId}.`);
         }
-        const runWorkspace = activeTurn?.workspace;
+        const purpose = activeRun?.purpose
+            ?? (task.status === "draft" && role.name === "leader" ? "planning" : "execution");
+        if (!runPurposeAdmitsTaskState(purpose, task)) {
+            throw new Error(`Task execution is not enabled: ${input.taskId}.`);
+        }
+        // A launch owns no managed workspace in two cases: a Draft planning
+        // conversation, and a Task activated with an empty environment plan. Both
+        // run with no Project entries, so there is nothing to preflight and no
+        // worktree to wait for. Every other fence — live Session, replaceable
+        // Conversation, configured Agent, Context protocol identity, adopted
+        // execution environment — still applies.
+        const planningDraft = purpose === "planning" && task.status === "draft";
+        // A planning cwd is a disposable per-Task runtime resource, not a delivery
+        // workspace. Materialize only the exact directory selected at creation.
+        if (planningDraft && resolve(role.workspace) === resolve(`${this.home}.task-runtimes`, "planning", task.id)) {
+            mkdirSync(role.workspace, { recursive: true, mode: 0o700 });
+        }
+        const workspaceFree = planningDraft || !taskOwnsManagedWorkspace(task);
+        // An empty resource plan is a legal Task shape, but it does not make a
+        // shared directory a legal cwd. Once such a Task is active it can name the
+        // directory it means through the existing environment plan, so require that
+        // instead of silently running in whatever workspace the Role inherited with
+        // isolation skipped.
+        if (workspaceFree && !planningDraft && role.executionEnvironment === undefined) {
+            throw new Error(`Task ${task.id} owns no workspace and no adopted execution environment, so Role `
+                + `${role.name} has no directory of its own to run in. Request activation with a `
+                + "`scratch` or `local` environment plan, or bind an adopted environment with "
+                + "`environment.bind`, instead of inheriting a shared workspace.");
+        }
+        const runWorkspace = activeRun?.workspace;
         const main = this.store.getTaskWorkspace(task.id);
         // Quick Win (EXE-04/EXE-08): classify workspace preflight failures so
         // split-brain state is never reported as a transient Provider failure.
-        const preflight = classifyWorkspacePreflight(this.store, task, input.roleName, activeTurn === null ? null : { id: activeTurn.id, workspace: activeTurn.workspace }, this.#inspectWorkspacePhysicalState);
+        const preflight = workspaceFree ? null : classifyWorkspacePreflight(this.store, task, input.roleName, activeRun === null ? null : { id: activeRun.id, workspace: activeRun.workspace }, this.#inspectWorkspacePhysicalState);
         if (preflight !== null) {
             throw new Error(formatWorkspacePreflightError(preflight));
         }
         const assignedWorkItem = this.store.listWorkItems(task.id).find((item) => item.assignee === role.name
-            && !["completed", "failed", "retired"].includes(item.status));
-        // A Turn snapshot is authoritative for the live launch. In particular,
-        // a Reviewer Turn must launch from its ReviewRound-owned workspace rather
+            && !["accepted", "retired"].includes(item.status));
+        // A AgentRun snapshot is authoritative for the live launch. In particular,
+        // a Reviewer AgentRun must launch from its ReviewRound-owned workspace rather
         // than falling back to the WorkItem Develop workspace.  Without an
         // active snapshot, resolve the normal Role/WorkItem assignment.
         const workspace = runWorkspace !== undefined
@@ -109,7 +153,12 @@ export class FileRoleLaunchPlanner {
                 : assignedWorkItem === undefined
                     ? main
                     : this.store.getWorkItemWorkspace(task.id, assignedWorkItem.id);
-        if (task.projectBindings.length === 0) {
+        if (workspaceFree) {
+            if (workspace !== null && !isDeepStrictEqual(workspace, main)) {
+                throw new Error(`Role workspace is not ready: ${input.taskId}/${input.roleName}.`);
+            }
+        }
+        else if (task.projectBindings.length === 0) {
             if (workspace === null || !isDeepStrictEqual(workspace, main)) {
                 throw new Error(`Role workspace is not ready: ${input.taskId}/${input.roleName}.`);
             }
@@ -126,9 +175,9 @@ export class FileRoleLaunchPlanner {
                 && workspace.owner.type === "work-item"
                 && isolatedWorkItem !== null
                 && (isolatedWorkItem.assignee === undefined || isolatedWorkItem.assignee === role.name)
-                && !["completed", "failed", "retired"].includes(isolatedWorkItem.status)
-                && (activeTurn === null
-                    || activeTurn.workItemId === workspace.owner.workItemId)
+                && !["accepted", "retired"].includes(isolatedWorkItem.status)
+                && (activeRun === null
+                    || activeRun.workItemId === workspace.owner.workItemId)
                 && sameWorkspaceProjects(workspace, task.projectBindings.map(({ projectId }) => projectId))
                 && sameWritableProjects(workspace, isolatedWorkItem.writeProjectIds);
             const runScoped = runWorkspace !== undefined
@@ -136,29 +185,29 @@ export class FileRoleLaunchPlanner {
                 && sameWorkspaceProjects(runWorkspace, task.projectBindings.map(({ projectId }) => projectId))
                 && (runWorkspace.owner.type === "task"
                     || (runWorkspace.owner.type === "work-item"
-                        && runWorkspace.owner.workItemId === activeTurn?.workItemId)
+                        && runWorkspace.owner.workItemId === activeRun?.workItemId)
                     || (runWorkspace.owner.type === "review-round"
-                        && activeTurn?.purpose === "review"
-                        && runWorkspace.owner.reviewRoundId === activeTurn.reviewRoundId)
+                        && activeRun?.purpose === "review"
+                        && runWorkspace.owner.reviewRoundId === activeRun.reviewRoundId)
                     || (runWorkspace.owner.type === "execution-lane"
-                        && runWorkspace.owner.executionGroupId === activeTurn?.executionGroupId
-                        && runWorkspace.owner.executionLaneId === activeTurn?.executionLaneId
-                        && ((runWorkspace.owner.purpose === "review" && activeTurn?.purpose === "review")
-                            || (runWorkspace.owner.purpose === "execution" && activeTurn?.purpose === "execution"))));
+                        && runWorkspace.owner.executionGroupId === activeRun?.executionGroupId
+                        && runWorkspace.owner.executionLaneId === activeRun?.executionLaneId
+                        && ((runWorkspace.owner.purpose === "review" && activeRun?.purpose === "review")
+                            || (runWorkspace.owner.purpose === "execution" && activeRun?.purpose === "execution"))));
             if (!runScoped && !sharedMain && !isolated) {
                 throw new Error(`Role workspace is not ready: ${input.taskId}/${input.roleName}.`);
             }
         }
         const sessionSet = this.store.getTaskRoleSessionSet(task.id, role.name);
-        const resolvedEffective = activeTurn?.effective
+        const resolvedEffective = activeRun?.effective
             ?? activeLiveRoleAgentSession(sessionSet)?.effective
-            ?? resolveTaskRoleEffectiveLaunch(this.store, role);
+            ?? resolveTaskRoleEffectiveLaunch(this.store, role, planningDraft ? "planning" : "execution");
         if (input.effective !== undefined
             && !isDeepStrictEqual(resolvedEffective, input.effective)) {
-            throw new Error(`Role launch effective Turn snapshot changed: ${input.taskId}/${input.roleName}.`);
+            throw new Error(`Role launch effective AgentRun snapshot changed: ${input.taskId}/${input.roleName}.`);
         }
-        if (activeTurn !== null && input.effective === undefined) {
-            throw new Error(`Role launch is missing the effective Turn snapshot: ${input.taskId}/${input.roleName}.`);
+        if (activeRun !== null && input.effective === undefined) {
+            throw new Error(`Role launch is missing the effective AgentRun snapshot: ${input.taskId}/${input.roleName}.`);
         }
         const effective = input.effective ?? resolvedEffective;
         const existing = sessionSet?.sessions[effective.agentId];
@@ -179,7 +228,7 @@ export class FileRoleLaunchPlanner {
             assertProviderConversationReplaceable(sessionSet.providerBinding);
         }
         return this.#compile(role, input, { scope: "task", taskId: task.id }, resolveTaskRoleSessionTitle(input.mode === "resume" ? existing?.title : undefined, task, role.name), input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, runWorkspace, effective, {
-            purpose: activeTurn?.purpose ?? "execution"
+            purpose
         });
     }
     planGlobalRole(input) {
@@ -206,14 +255,40 @@ export class FileRoleLaunchPlanner {
         const launchRole = effectiveRoleForLaunch(role, effective);
         const binding = activeRoleAgentBinding(launchRole);
         if (binding.agentId !== input.agentId || binding.adapterId !== input.adapterId) {
-            throw new Error(`Role runtime generation identity changed: ${role.name}.`);
-        }
+            throw new Error(`Role runtime identity changed: ${role.name}.`);
+        }
+        const existingSession = owner.scope === "task"
+            ? this.store.getTaskRoleSessionSet(owner.taskId, role.name)?.sessions[input.agentId]
+            : this.store.getGlobalRoleSessionSet(role.name)?.sessions[input.agentId];
+        // A resume carries the Session's recorded generation forward unchanged. This
+        // planner runs in the Controller, which after an upgrade is already the new
+        // code, so it cannot speak for the still-running Agent Host that owns the
+        // Session: rejecting here would end live Sessions on Controller upgrade,
+        // while rewriting to current code would silently move a Session onto code it
+        // never started on. The Host that actually executes the implementation makes
+        // the decision — a reused live Host accepts its own generation, and a newly
+        // started Host running different code fails closed
+        // (`agentEndpointOwnership.pin` -> `requireBuiltinAgentEndpointImplementation`).
+        const endpointImplementation = input.mode === "resume"
+            ? validateAgentEndpointImplementation(existingSession.endpointImplementation)
+            : builtinAgentEndpointImplementation(binding.adapterId);
         const configured = this.store.getConfiguredAgent(input.agentId);
         if (configured === null)
             throw new Error(`Configured Agent not found: ${input.agentId}.`);
         if (configured.adapterId !== binding.adapterId) {
             throw new Error(`Configured Agent adapter changed: ${input.agentId}.`);
         }
+        // The command below comes from the Agent record while the product identity
+        // stamped onto this Session comes from the pinned snapshot. Checking only
+        // the adapter lets those disagree whenever two products share a plan, which
+        // is exactly the ACP case: the launch would run the newly configured
+        // executable and label it with the product the Session was pinned to. The
+        // update path refuses this change on a referenced Agent, so reaching here
+        // means the record was altered some other way — still not something to
+        // launch through.
+        if (configured.component !== binding.component) {
+            throw new Error(`Configured Agent execution component changed: ${input.agentId}.`);
+        }
         const agent = configuredAgentToDefinition(configured);
         const agentSourceEnvironment = input.environment ?? this.#agentEnvironment;
         const operationalSourceEnvironment = input.environment ?? {
@@ -228,8 +303,20 @@ export class FileRoleLaunchPlanner {
         const launchEnvironment = { ...inheritedLaunchEnvironment };
         const adapter = resolveAgentAdapter(binding.adapterId);
         const effectiveWorkspace = effective.workspace.root;
-        const agentWorkspace = nativeAgentWorkspace(effective.workspace);
-        if (adapter.id === "codex" && (owner.scope !== "task" || input.turnId === undefined)) {
+        if (effective.executionEnvironment !== undefined) {
+            if (owner.scope !== "task")
+                throw new Error("Global Roles cannot adopt a Task execution environment.");
+            assertExecutionEnvironmentCurrent(this.store, owner.taskId, effective.executionEnvironment);
+            if ((binding.config.advanced?.rawArgs?.length ?? 0) > 0) {
+                throw new Error("Adopted environments do not accept raw Agent arguments; use structured configuration.");
+            }
+            if ((binding.config.additionalDirectories?.length ?? 0) > 0) {
+                throw new Error("Adopted environments cannot implicitly include additional directories.");
+            }
+        }
+        const agentWorkspace = effective.executionEnvironment?.directory.path
+            ?? nativeAgentWorkspace(effective.workspace);
+        if (adapter.id === "codex" && (owner.scope !== "task" || input.runId === undefined)) {
             const codexConfig = inspectCodexLaunchConfig({
                 environment: launchEnvironment,
                 workspace: agentWorkspace,
@@ -245,10 +332,7 @@ export class FileRoleLaunchPlanner {
         const runtimeIsolation = input.runtimeIsolation === undefined
             ? undefined
             : parseTaskRuntimeIsolationDescriptor(JSON.stringify(input.runtimeIsolation));
-        if (runtimeIsolation !== undefined && (owner.scope !== "task"
-            || runtimeIsolation.taskId !== owner.taskId
-            || runtimeIsolation.workspace.root !== effectiveWorkspace
-            || runtimeIsolation.generation.runtimeGenerationId !== input.runtimeGenerationId)) {
+        if (runtimeIsolation !== undefined && (owner.scope !== "task" || runtimeIsolation.taskId !== owner.taskId || runtimeIsolation.workspace.root !== effectiveWorkspace)) {
             throw new Error("Role launch does not match its Task runtime isolation descriptor.");
         }
         Object.assign(launchEnvironment, runtimeIsolation === undefined
@@ -276,23 +360,25 @@ export class FileRoleLaunchPlanner {
             sessionManifestDigest: bootstrap.manifest.digest,
             sessionCliPath: bootstrap.sessionCliPath
         };
-        const managedRun = owner.scope === "task" && input.turnId !== undefined
-            ? this.store.getTurn(owner.taskId, input.turnId)
+        const managedRun = owner.scope === "task" && input.runId !== undefined
+            ? this.store.getRun(owner.taskId, input.runId)
             : null;
         const driver = builtinAgentDriverRegistry().require(builtinDriverIdForAdapter(configured.adapterId));
-        if (owner.scope === "task" && input.turnId !== undefined) {
+        if (owner.scope === "task" && input.runId !== undefined) {
             const admission = managedRuntimeAdmission(driver.capabilities);
             if (!admission.admitted) {
-                throw new Error(`Agent Driver ${driver.id} cannot host managed Turns; missing capabilities: `
+                throw new Error(`Agent Driver ${driver.id} cannot host managed AgentRuns; missing capabilities: `
                     + admission.missing.join(", "));
             }
         }
         const roleConfig = binding.config.adapterId === "claude"
             && owner.scope === "task"
-            && input.turnId !== undefined
-            ? managedClaudeControlPlaneConfig(binding.config, owner.taskId, managedRun?.workItemId, input.turnId)
+            && input.runId !== undefined
+            ? managedClaudeControlPlaneConfig(binding.config, owner.taskId, managedRun?.workItemId, input.runId)
             : binding.config;
-        const effectiveConfig = withNativeProjectDirectories(roleConfig, nativeAdditionalDirectories(effective.workspace, agentWorkspace));
+        const effectiveConfig = withNativeProjectDirectories(roleConfig, effective.executionEnvironment === undefined
+            ? nativeAdditionalDirectories(effective.workspace, agentWorkspace)
+            : []);
         const compileInput = {
             agent,
             config: effectiveConfig,
@@ -307,27 +393,20 @@ export class FileRoleLaunchPlanner {
         }
         // A previous attempt may have persisted a preallocated/discovered ID
         // before its receipt was committed. Reuse that fixed session rather than
-        // allocating a second native session for the same durable Turn.
+        // allocating a second native session for the same durable AgentRun.
         const resumeNativeSessionId = input.mode === "resume"
             ? requireText(input.nativeSessionId, "Native session id")
             : knownNativeSessionId;
         const launchMode = resumeNativeSessionId === undefined
             ? "new"
             : "resume";
-        const managedControl = owner.scope === "task" && input.turnId !== undefined;
-        const managedProviderEnvironment = managedControl
-            && configured.adapterId === "codex"
-            ? {
-                // Managed Codex Turns are non-interactive. Use the Codex execution
-                // identity for provider requests while clientInfo still identifies Yui.
-                CODEX_INTERNAL_ORIGINATOR_OVERRIDE: "codex_exec"
-            }
-            : {};
-        const preallocatedNativeSessionId = binding.adapterId === "claude"
+        const managedControl = owner.scope === "task";
+        // Only an Agent that accepts a caller-chosen Session id can have one
+        // preallocated. Keying this on the adapter name instead of the declared
+        // capability meant every non-Claude adapter was assumed to accept one.
+        const preallocatedNativeSessionId = adapter.capabilities.nativeSessionDiscovery === "preallocated"
             && resumeNativeSessionId === undefined
-            ? requireText(input.runtimeGenerationId === undefined
-                ? this.#createNativeSessionId()
-                : nativeSessionIdForLaunch(this.home, input.runtimeGenerationId, input.agentId, input.adapterId), "Native session id")
+            ? requireText(this.#createNativeSessionId(), "Native session id")
             : resumeNativeSessionId;
         const managedCompiled = managedControl
             ? adapter.compileManagedControl(compileInput, launchMode, preallocatedNativeSessionId)
@@ -363,17 +442,14 @@ export class FileRoleLaunchPlanner {
         }
         if (binding.adapterId === "codex") {
             // Interactive Task sessions may use notify for presentation.
-            // Managed Turns receive lifecycle facts through their ordinary App Server
-            // subscription, avoiding a second Hook channel for the same Turn.
-            if (owner.scope === "task" && input.turnId === undefined) {
-                args = addCodexSessionNotify(args, launchMode, this.#cliPath);
-            }
+            // Managed AgentRuns receive lifecycle facts through their ordinary App Server
+            // subscription, avoiding a second Hook channel for the same AgentRun.
             // Managed Codex Turns use disposable proxy clients against the shared
             // native App Server. Their Session Manifest points at the Yui Skills;
             // no Yui Hook config is installed.
-            if (owner.scope === "task" && input.turnId !== undefined) {
+            if (owner.scope === "task" && input.runId !== undefined) {
                 if (managedRun === null || managedRun.status !== "active") {
-                    throw new Error(`Managed Codex Turn is no longer active: ${input.turnId}.`);
+                    throw new Error(`Managed Codex AgentRun is no longer active: ${input.runId}.`);
                 }
             }
             session = launchMode === "resume"
@@ -381,41 +457,41 @@ export class FileRoleLaunchPlanner {
                 : null;
         }
         else if (launchMode === "new") {
-            const nativeSessionId = requireText(preallocatedNativeSessionId, "Native session id");
-            if (!managedControl)
-                args.push("--session-id", nativeSessionId);
-            else if (!args.includes("--session-id"))
-                args.push("--session-id", nativeSessionId);
-            session = readySession(input.agentId, binding.adapterId, nativeSessionId, effective);
+            if (adapter.capabilities.nativeSessionDiscovery === "preallocated") {
+                const nativeSessionId = requireText(preallocatedNativeSessionId, "Native session id");
+                if (!managedControl)
+                    args.push("--session-id", nativeSessionId);
+                else if (!args.includes("--session-id"))
+                    args.push("--session-id", nativeSessionId);
+                session = readySession(input.agentId, binding.adapterId, nativeSessionId, effective);
+            }
+            else {
+                // A runtime-discovered Session id does not exist until the Agent
+                // answers, so there is no ready Session to record at plan time and no
+                // id to pass on the command line. Same shape as a new Codex launch.
+                session = null;
+            }
         }
         else {
             session = readySession(input.agentId, binding.adapterId, resumeNativeSessionId, effective);
         }
         const managedClaudeRun = binding.adapterId === "claude"
             && owner.scope === "task"
-            && input.turnId !== undefined;
+            && input.runId !== undefined;
         if (managedClaudeRun && (managedRun === null || managedRun.status !== "active")) {
-            throw new Error(`Managed Claude Turn is no longer active: ${input.turnId}.`);
+            throw new Error(`Managed Claude AgentRun is no longer active: ${input.runId}.`);
         }
-        // Generate a candidate per-Provider-process DurableJob caller key for
-        // every task-scope launch. A reused live Conversation keeps the key that
-        // its process inherited; a new Host or a Conversation replacement commits
-        // the fresh candidate only after Provider dispatch is observed.
-        let jobCallerKey;
-        if (owner.scope === "task" && (input.mode === "new" || input.mode === "resume")) {
-            jobCallerKey = randomBytes(32).toString("hex");
-        }
-        // Session lifecycle and Turn submission are separate atomic operations.
+        // Session lifecycle and AgentRun submission are separate atomic operations.
         // Planning only starts or restores the exact native Session; delivery
-        // submits the Turn input after that Session fact is durable.
-        if (managedControl && (managedRun === null || managedRun.status !== "active")) {
-            throw new Error(`Managed Turn is no longer active: ${input.turnId}.`);
+        // submits the AgentRun input after that Session fact is durable.
+        if (managedControl && input.runId !== undefined && (managedRun === null || managedRun.status !== "active")) {
+            throw new Error(`Managed AgentRun is no longer active: ${input.runId}.`);
         }
         const providerAuthority = managedControl
-            ? this.#providerAuthorityForLaunch(owner.taskId, role.name, input.runtimeGenerationId, input.mode)
+            ? this.#providerAuthorityForLaunch(owner.taskId, role.name, input.mode)
             : undefined;
-        const providerOwnedTurn = managedControl && input.mode === "resume"
-            ? this.#providerOwnedTurnForLaunch(owner.taskId, role.name, input.turnId)
+        const providerOwnedRun = managedControl && input.mode === "resume" && input.runId !== undefined
+            ? this.#providerOwnedRunForLaunch(owner.taskId, role.name, input.runId)
             : undefined;
         const providerNativeSessionId = binding.adapterId === "claude"
             ? preallocatedNativeSessionId
@@ -426,22 +502,35 @@ export class FileRoleLaunchPlanner {
                 ? {
                     schemaVersion: 1,
                     adapterId: binding.adapterId,
+                    // The product identity is pinned by the snapshot this launch was
+                    // resolved from, and the check above proves the Agent record still
+                    // names it. Carrying only the adapter would leave the runtime with
+                    // two products sharing one plan and no way to tell them apart.
+                    component: binding.component,
                     transport: managedCompiled.transport,
+                    endpointImplementation,
                     kind: "restore",
+                    sessionOnly: input.runId === undefined,
                     mode: "resume",
                     nativeSessionId: requireText(providerNativeSessionId, "Managed Provider restore native session id"),
                     ...(sessionTitle === undefined ? {} : { sessionTitle }),
                     ...(managedCompiled.codexThread === undefined
                         ? {}
                         : { codexThread: managedCompiled.codexThread }),
-                    ...(providerOwnedTurn === undefined ? {} : { ownedTurn: providerOwnedTurn }),
+                    ...(providerOwnedRun === undefined ? {} : { ownedTurn: providerOwnedRun }),
+                    ...(managedCompiled.acpSession === undefined
+                        ? {}
+                        : { acpSession: managedCompiled.acpSession }),
                     authority: providerAuthority
                 }
                 : {
                     schemaVersion: 1,
                     adapterId: binding.adapterId,
+                    component: binding.component,
                     transport: managedCompiled.transport,
+                    endpointImplementation,
                     kind: "start",
+                    sessionOnly: input.runId === undefined,
                     mode: "new",
                     ...(providerNativeSessionId === undefined
                         ? {}
@@ -450,15 +539,23 @@ export class FileRoleLaunchPlanner {
                     ...(managedCompiled.codexThread === undefined
                         ? {}
                         : { codexThread: managedCompiled.codexThread }),
+                    ...(managedCompiled.acpSession === undefined
+                        ? {}
+                        : { acpSession: managedCompiled.acpSession }),
                     authority: providerAuthority
                 };
         const launch = {
             command,
             args,
+            ...(effective.executionEnvironment === undefined ? {} : {
+                executionEnvironment: structuredClone(effective.executionEnvironment)
+            }),
             ...(providerControl === undefined ? {} : { providerControl }),
+            ...(owner.scope === "global" && binding.adapterId === "codex"
+                ? { interactiveCodexThread: compiled.codexThread }
+                : {}),
             env: {
                 ...launchEnvironment,
-                ...managedProviderEnvironment,
                 YUI_HOME: resolve(this.home),
                 YUI_SESSION_SCOPE: owner.scope,
                 ...(owner.scope === "task" ? { YUI_TASK_ID: owner.taskId } : {}),
@@ -469,10 +566,9 @@ export class FileRoleLaunchPlanner {
                 YUI_WORKSPACE: effectiveWorkspace,
                 YUI_SESSION_MANIFEST: sessionContext.sessionManifestPath,
                 YUI_SESSION_CLI: sessionContext.sessionCliPath,
-                ...(owner.scope === "global" && configured.adapterId === "codex"
+                ...(configured.adapterId === "codex"
                     ? { YUI_AGENT_BASE_ARGS: JSON.stringify(configured.baseArgs) }
                     : {}),
-                ...(jobCallerKey === undefined ? {} : { YUI_JOB_CALLER_KEY: jobCallerKey }),
                 ...(sessionTitle === undefined
                     ? {}
                     : {
@@ -484,13 +580,10 @@ export class FileRoleLaunchPlanner {
                             }
                             : {})
                     }),
-                ...(input.runtimeGenerationId === undefined
-                    ? {}
-                    : { YUI_RUNTIME_GENERATION_ID: input.runtimeGenerationId }),
-                // No Turn is exported into the Session environment. A native pane
-                // outlives its Turn, so a Turn id frozen here would be stale for every
-                // later Turn. The Agent Host sets it explicitly per spawned Provider
-                // Turn, and every durable decision reads the active Turn from state.
+                // No AgentRun is exported into the Session environment. A native pane
+                // outlives its AgentRun, so a AgentRun id frozen here would be stale for every
+                // later AgentRun. The Agent Host sets it explicitly per spawned Provider
+                // AgentRun, and every durable decision reads the active AgentRun from state.
                 ...(session === null
                     ? {}
                     : { YUI_NATIVE_SESSION_ID: session.nativeSessionId })
@@ -518,24 +611,17 @@ export class FileRoleLaunchPlanner {
             ...(sessionTitle === undefined ? {} : { sessionTitle })
         };
     }
-    #providerAuthorityForLaunch(taskId, roleName, runtimeGenerationId, mode) {
-        const activationId = requireText(runtimeGenerationId, "Managed Provider Activation id");
+    #providerAuthorityForLaunch(taskId, roleName, mode) {
         const binding = this.store.getTaskRoleSessionSet(taskId, roleName)?.providerBinding;
         if (binding === null || binding === undefined) {
-            return { epoch: 1, owner: "controller", holderId: activationId };
+            return { epoch: 1, owner: "controller", holderId: "controller" };
         }
         if (binding.authority.owner === "controller") {
             if (mode === "new") {
-                const activation = currentProviderActivation(binding);
-                if (activation === null || binding.authority.holderId !== activation.activationId) {
-                    throw new Error(`Provider Activation is not exact: ${taskId}/${roleName}.`);
-                }
-                // An actor-requested switch first ends the idle old Activation (+1)
-                // and then binds the replacement Activation (+1).
                 return {
-                    epoch: binding.authority.epoch + 2,
+                    epoch: binding.authority.epoch + 1,
                     owner: "controller",
-                    holderId: activationId
+                    holderId: "controller"
                 };
             }
             return {
@@ -551,32 +637,32 @@ export class FileRoleLaunchPlanner {
             return {
                 epoch: binding.authority.epoch + 1,
                 owner: "controller",
-                holderId: activationId
+                holderId: "controller"
             };
         }
         throw new Error(`Provider writer authority is unknown: ${taskId}/${roleName}.`);
     }
-    #providerOwnedTurnForLaunch(taskId, roleName, turnId) {
+    #providerOwnedRunForLaunch(taskId, roleName, runId) {
         const binding = this.store.getTaskRoleSessionSet(taskId, roleName)?.providerBinding;
         if (binding === null || binding === undefined
-            || binding.turn?.turnId !== turnId)
+            || binding.run?.runId !== runId)
             return undefined;
-        const turn = binding.turn;
-        if (turn === null || turn.status !== "accepted")
+        const run = binding.run;
+        if (run === null || run.status !== "accepted")
             return undefined;
-        if (turn.nativeTurnId === undefined) {
-            throw new Error(`Active Provider Turn has no native identity: ${taskId}/${roleName}.`);
+        if (run.nativeTurnId === undefined) {
+            throw new Error(`Active Provider AgentRun has no native identity: ${taskId}/${roleName}.`);
         }
-        return { attemptId: turn.attemptId, turnId: turn.nativeTurnId };
+        return { attemptId: run.attemptId, turnId: run.nativeTurnId };
     }
     #applyWorkspaceScope(taskId, role, launch, workspaceOverride) {
         const workspace = workspaceOverride
             ?? (role.name === "leader"
                 ? this.store.getTaskWorkspace(taskId)
                 : this.store.listWorkItems(taskId)
-                    .find((item) => item.assignee === role.name && item.status === "running") === undefined
+                    .find((item) => item.assignee === role.name && item.status === "open") === undefined
                     ? this.store.getTaskWorkspace(taskId)
-                    : this.store.getWorkItemWorkspace(taskId, this.store.listWorkItems(taskId).find((item) => item.assignee === role.name && item.status === "running").id));
+                    : this.store.getWorkItemWorkspace(taskId, this.store.listWorkItems(taskId).find((item) => item.assignee === role.name && item.status === "open").id));
         if (workspace === null || workspace === undefined)
             return launch;
         return {
@@ -622,9 +708,14 @@ export function withNativeProjectDirectories(config, projectDirectories) {
             ])]
     };
 }
-function resolveTaskRoleEffectiveLaunch(store, role) {
+function resolveTaskRoleEffectiveLaunch(store, role, purpose = "execution") {
+    if (purpose === "planning") {
+        // Planning has no WorkItem assignment and no managed workspace, so it
+        // resolves the Role's own configured workspace with no writable Project.
+        return resolveEffectiveLaunch({ role, purpose: "planning" });
+    }
     const item = store.listWorkItems(role.taskId).find((candidate) => (candidate.assignee === role.name
-        && !["completed", "failed", "retired"].includes(candidate.status))) ?? null;
+        && !["accepted", "retired"].includes(candidate.status))) ?? null;
     const workspace = (item === null
         ? store.getTaskWorkspace(role.taskId)
         : store.getWorkItemWorkspace(role.taskId, item.id))
@@ -684,11 +775,11 @@ function ensureClaudeLifecyclePlugin(home, cliPath) {
     }, null, 2)}\n`);
     return root;
 }
-function managedClaudeControlPlaneConfig(config, taskId, workItemId, turnId) {
+function managedClaudeControlPlaneConfig(config, taskId, workItemId, runId) {
     if (config.permission.strategy !== "configured")
         return config;
     const managed = [
-        `Bash(yui task turn context ${taskId}/${turnId}:*)`,
+        `Bash(yui task run context ${taskId}/${runId}:*)`,
         `Bash(yui --json task context ${taskId})`,
         `Bash(yui --json task work list ${taskId})`,
         ...(workItemId === undefined
@@ -751,22 +842,6 @@ function patchEnvironment(current, names, values) {
         next[name] = value;
     return next;
 }
-/**
- * Codex invokes this argv after each completed turn and appends one JSON
- * payload. JSON arrays are valid TOML arrays for the managed config override.
- */
-export function codexSessionNotifyConfig(cliPath) {
-    return `notify=${JSON.stringify([process.execPath, cliPath, "internal", "session-notify"])}`;
-}
-function addCodexSessionNotify(args, mode, cliPath) {
-    const managed = ["--config", codexSessionNotifyConfig(cliPath)];
-    if (mode === "new")
-        return [...args, ...managed];
-    if (args.length < 2 || args.at(-2) !== "resume") {
-        throw new Error("Codex resume launch shape is invalid.");
-    }
-    return [...args.slice(0, -2), ...managed, ...args.slice(-2)];
-}
 /**
  * Global Codex keeps its native TUI, but the TUI is only a client attachment
  * to the user's shared App Server. The daemon owns the Thread and its writer,
@@ -798,7 +873,7 @@ function codexShellEnvironmentConfig(environment) {
 /**
  * Codex 0.145 discovers lifecycle hooks from its effective config. Keep Yui's
  * two handlers invocation-local: this avoids mutating CODEX_HOME or the Task
- * workspace, while the exact launch environment supplies the durable Turn fence.
+ * workspace, while the exact launch environment supplies the durable AgentRun fence.
  */
 function codexLifecycleHooksConfig(cliPath) {
     const command = [