@zq-silk/yui 0.2.0 → 0.4.2

package/dist/executor/fileRoleLaunchPlanner.js

@@ -1,23 +1,88 @@
 import { randomUUID } from "node:crypto";
-import { resolve } from "node:path";
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
 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";
+import { writeTextFileAtomically } from "../storage/durableFile.js";
+import { compileRoleSessionContext } from "../context/roleSessionContext.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
+import { inspectCodexLaunchConfig } from "./codexConfigConflict.js";
+import { taskRoleSessionTitle } from "../runtime/sessionTitle.js";
+import { nativeSessionIdForLaunch } from "../runtime/preallocatedNativeSession.js";
+import { isTaskOwnedWorkspace } from "../worktree/managedWorkspace.js";
+import { activeLiveRoleAgentSession } from "./agentExecutor.js";
+import { effectiveLaunchSnapshotsCompatible, effectiveRoleForLaunch, resolveEffectiveLaunch } from "./effectiveLaunch.js";
+import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR, assertExactTaskRuntimeState, createExactControlPlaneDescriptor, createExactTaskRuntimeDescriptor, exactControlPlaneCommandPrefix, exactControlPlaneDigest, exactTaskRuntimeDescriptorPath, serializeExactDescriptor } from "../runtime/exactControlPlane.js";
+import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
 /** Builds managed native Agent launches from the authoritative Task records. */
 export class FileRoleLaunchPlanner {
     home;
     store;
-    #environment;
+    #operationalEnvironment;
+    #agentEnvironment;
+    #nativeAgentEnvironment;
     #createNativeSessionId;
     #cliPath;
+    #controlPlane;
     constructor(home, store, options = {}) {
         this.home = home;
         this.store = store;
-        this.#environment = options.environment ?? process.env;
+        // Operational launch context is stable for the Controller lifetime. Agent
+        // binding sources are a separate replaceable snapshot so an unset/removed
+        // secret cannot survive a later configuration refresh.
+        const sourceEnvironment = { ...(options.environment ?? process.env) };
+        this.#operationalEnvironment = { ...sourceEnvironment };
+        for (const name of NATIVE_AGENT_ENVIRONMENT_NAMES) {
+            delete this.#operationalEnvironment[name];
+        }
+        this.#agentEnvironment = this.#selectConfiguredAgentEnvironment(sourceEnvironment);
+        this.#nativeAgentEnvironment = this.#selectConfiguredNativeEnvironment(sourceEnvironment);
         this.#createNativeSessionId = options.createNativeSessionId ?? randomUUID;
-        this.#cliPath = options.cliPath
-            ?? fileURLToPath(new URL("../cli.js", import.meta.url));
+        this.#cliPath = canonicalPath(options.cliPath
+            ?? fileURLToPath(new URL("../cli.js", import.meta.url)));
+        // Freeze the complete control identity before any native process exists.
+        // This value is immutable for the planner/Controller lifetime and is never
+        // rewritten through a shared PATH launcher.
+        this.#controlPlane = createExactControlPlaneDescriptor({
+            executable: process.execPath,
+            cliEntry: this.#cliPath,
+            yuiHome: this.home
+        });
+    }
+    refreshAgentEnvironment(refresh) {
+        this.#agentEnvironment = patchEnvironment(this.#agentEnvironment, refresh.sourceNames, refresh.sources);
+        this.#nativeAgentEnvironment = patchEnvironment(this.#nativeAgentEnvironment, refresh.nativeNames, refresh.nativeSources);
+    }
+    /** Re-publishes provider-discovered native identity after its durable fold. */
+    refreshTaskRuntimeDescriptor(input) {
+        const task = this.store.getTask(input.taskId);
+        const role = this.store.getRole(input.taskId, input.roleName);
+        if (task === null || task.status !== "active" || role === null) {
+            throw new Error(`Task runtime is not current: ${input.taskId}/${input.roleName}.`);
+        }
+        const run = this.store.getActiveAgentRun(input.taskId, input.roleName);
+        const sessions = this.store.getTaskRoleSessionSet(input.taskId, input.roleName);
+        const session = sessions?.sessions[role.activeAgentId];
+        if (session === undefined || session.launchId === undefined) {
+            throw new Error(`Task runtime native Session is not ready: ${input.taskId}/${input.roleName}.`);
+        }
+        const effective = run?.effective ?? session.effective;
+        const descriptor = createExactTaskRuntimeDescriptor({
+            controlPlaneDigest: exactControlPlaneDigest(this.#controlPlane),
+            taskId: input.taskId,
+            roleName: input.roleName,
+            agentId: session.agentId,
+            adapterId: session.adapterId,
+            workspace: effective.workspace.root,
+            ...(run === null ? {} : { runId: run.id }),
+            launchId: session.launchId,
+            nativeSessionId: session.nativeSessionId
+        });
+        assertExactTaskRuntimeState(descriptor, this.store);
+        writeTextFileAtomically(exactTaskRuntimeDescriptorPath(this.home, descriptor), `${serializeExactDescriptor(descriptor)}\n`);
     }
     plan(input) {
         const task = this.store.getTask(input.taskId);
@@ -28,25 +93,119 @@ export class FileRoleLaunchPlanner {
         const role = this.store.getRole(input.taskId, input.roleName);
         if (role === null)
             throw new Error(`Role not found: ${input.taskId}/${input.roleName}.`);
-        if (task.repositoryId !== undefined) {
-            const workspace = this.store.getRoleWorkspace(task.id, role.name);
-            if (task.cwd === undefined
-                || workspace === null
-                || workspace.repositoryId !== task.repositoryId
-                || workspace.path !== role.workspace) {
+        const activeRun = this.store.getActiveAgentRun(task.id, role.name);
+        if (input.runId !== undefined && activeRun?.id !== input.runId) {
+            throw new Error(`Role Run is no longer current: ${input.runId}.`);
+        }
+        const runWorkspace = activeRun?.workspace;
+        const main = this.store.getTaskWorkspace(task.id);
+        if (!isTaskOwnedWorkspace(main, task.id, task.cwd, task.projectBindings.map(({ projectId, directory }) => ({ projectId, directory })))) {
+            throw new Error(`Role workspace is not ready: ${input.taskId}/${input.roleName}.`);
+        }
+        if (runWorkspace !== undefined) {
+            const durableRunWorkspace = this.store.getManagedWorkspace(runWorkspace.owner);
+            if (durableRunWorkspace === null || !isDeepStrictEqual(durableRunWorkspace, runWorkspace)) {
+                throw new Error(`Role Run workspace is not the durable owner: ${input.taskId}/${input.roleName}.`);
+            }
+        }
+        const assignedWorkItem = this.store.listWorkItems(task.id).find((item) => item.assignee === role.name
+            && !["completed", "failed", "retired"].includes(item.status));
+        // A Run snapshot is authoritative for the live launch.  In particular,
+        // a reviewer Run 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
+            ? runWorkspace
+            : task.projectBindings.length === 0
+                ? main
+                : assignedWorkItem === undefined
+                    ? main
+                    : this.store.getWorkItemWorkspace(task.id, assignedWorkItem.id);
+        if (task.projectBindings.length === 0) {
+            if (workspace === null || !isDeepStrictEqual(workspace, main)) {
+                throw new Error(`Role workspace is not ready: ${input.taskId}/${input.roleName}.`);
+            }
+        }
+        else {
+            const sharedMain = main !== null
+                && (workspace === null || workspace.owner.type === "task")
+                && sameWorkspaceProjects(main, task.projectBindings.map(({ projectId }) => projectId))
+                && (role.name === "leader" || role.workspace === main.root);
+            const isolatedWorkItem = workspace?.owner.type === "work-item"
+                ? this.store.getWorkItem(task.id, workspace.owner.workItemId)
+                : null;
+            const isolated = workspace !== null
+                && workspace.owner.type === "work-item"
+                && isolatedWorkItem !== null
+                && (isolatedWorkItem.assignee === undefined || isolatedWorkItem.assignee === role.name)
+                && !["completed", "failed", "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
+                && runWorkspace.owner.taskId === task.id
+                && sameWorkspaceProjects(runWorkspace, task.projectBindings.map(({ projectId }) => projectId))
+                && (runWorkspace.owner.type === "task"
+                    || (runWorkspace.owner.type === "work-item"
+                        && runWorkspace.owner.workItemId === activeRun?.workItemId)
+                    || (runWorkspace.owner.type === "review-round"
+                        && activeRun?.purpose === "review"
+                        && runWorkspace.owner.reviewRoundId === activeRun.reviewRoundId)
+                    || (runWorkspace.owner.type === "execution-lane"
+                        && 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}.`);
             }
         }
-        return this.#compile(role, input, { scope: "task", taskId: task.id }, this.store.getRoleSession(task.id, role.name)?.nativeSessionId);
+        const sessionSet = this.store.getTaskRoleSessionSet(task.id, role.name);
+        const resolvedEffective = activeRun?.effective
+            ?? activeLiveRoleAgentSession(sessionSet)?.effective
+            ?? resolveTaskRoleEffectiveLaunch(this.store, role);
+        if (input.effective !== undefined
+            && !isDeepStrictEqual(resolvedEffective, input.effective)) {
+            throw new Error(`Role launch effective Run snapshot changed: ${input.taskId}/${input.roleName}.`);
+        }
+        if (activeRun !== null && input.effective === undefined) {
+            throw new Error(`Role launch is missing the effective Run snapshot: ${input.taskId}/${input.roleName}.`);
+        }
+        const effective = input.effective ?? resolvedEffective;
+        const existing = sessionSet?.sessions[effective.agentId];
+        const compatibleExisting = existing !== undefined
+            && effectiveLaunchSnapshotsCompatible(existing.effective, effective);
+        if (input.mode === "resume" && !compatibleExisting) {
+            throw new Error(`Task Role resume effective snapshot drifted: ${task.id}/${role.name}.`);
+        }
+        return this.#compile(role, input, { scope: "task", taskId: task.id }, taskRoleSessionTitle(task, role.name), compatibleExisting ? existing.nativeSessionId : undefined, runWorkspace, effective, {
+            purpose: activeRun?.purpose ?? "execution"
+        });
     }
     planGlobalRole(input) {
         const role = this.store.getGlobalRole(input.roleName);
         if (role === null)
             throw new Error(`Global Role not found: ${input.roleName}.`);
-        return this.#compile(role, input, { scope: "global" }, this.store.getGlobalRoleSessionSet(role.name)?.sessions[role.activeAgentId]?.nativeSessionId);
+        const sessionSet = this.store.getGlobalRoleSessionSet(role.name);
+        const resolvedEffective = activeLiveRoleAgentSession(sessionSet)?.effective
+            ?? resolveEffectiveLaunch({ role, purpose: "execution" });
+        if (input.effective !== undefined
+            && !isDeepStrictEqual(resolvedEffective, input.effective)) {
+            throw new Error(`Global Role launch effective snapshot changed: ${role.name}.`);
+        }
+        const effective = input.effective ?? resolvedEffective;
+        const existing = sessionSet?.sessions[effective.agentId];
+        const compatibleExisting = existing !== undefined
+            && effectiveLaunchSnapshotsCompatible(existing.effective, effective);
+        if (input.mode === "resume" && !compatibleExisting) {
+            throw new Error(`Global Role resume effective snapshot drifted: ${role.name}.`);
+        }
+        return this.#compile(role, input, { scope: "global" }, undefined, compatibleExisting ? existing.nativeSessionId : undefined, undefined, effective, { purpose: "execution" });
     }
-    #compile(role, input, owner, knownNativeSessionId) {
-        const binding = activeRoleAgentBinding(role);
+    #compile(role, input, owner, sessionTitle, knownNativeSessionId, workspaceOverride, effective, sessionPolicy) {
+        const launchRole = effectiveRoleForLaunch(role, effective);
+        const binding = activeRoleAgentBinding(launchRole);
         if (binding.agentId !== input.agentId || binding.adapterId !== input.adapterId) {
             throw new Error(`Role launch identity changed: ${role.name}.`);
         }
@@ -57,12 +216,78 @@ export class FileRoleLaunchPlanner {
             throw new Error(`Configured Agent adapter changed: ${input.agentId}.`);
         }
         const agent = configuredAgentToDefinition(configured);
+        const agentSourceEnvironment = input.environment ?? this.#agentEnvironment;
+        const operationalSourceEnvironment = input.environment ?? {
+            ...this.#operationalEnvironment,
+            ...this.#nativeAgentEnvironment
+        };
+        const resolvedAgentEnvironment = resolveAgentEnvironment(agent, agentSourceEnvironment);
+        const inheritedLaunchEnvironment = {
+            ...operationalAgentEnvironment(configured.adapterId, operationalSourceEnvironment),
+            ...resolvedAgentEnvironment
+        };
+        const launchEnvironment = { ...inheritedLaunchEnvironment };
         const adapter = resolveAgentAdapter(binding.adapterId);
+        const effectiveWorkspace = effective.workspace.root;
+        const agentWorkspace = nativeAgentWorkspace(effective.workspace);
+        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.runId !== input.runId
+            || runtimeIsolation.generation.launchId !== input.launchId)) {
+            throw new Error("Role launch does not match its Task runtime isolation descriptor.");
+        }
+        Object.assign(launchEnvironment, runtimeIsolation === undefined
+            ? {}
+            : taskRuntimeIsolationEnvironment(runtimeIsolation));
+        const baseSessionContext = compileRoleSessionContext(this.home, launchRole, owner, sessionPolicy);
+        const sessionContext = owner.scope === "task"
+            ? {
+                ...baseSessionContext,
+                developerInstructions: [
+                    baseSessionContext.developerInstructions,
+                    renderExactControlPlaneInstructions(this.#controlPlane)
+                ].join("\n")
+            }
+            : baseSessionContext;
+        const codexConfig = binding.config.adapterId === "codex"
+            ? inspectCodexLaunchConfig({
+                environment: {
+                    ...operationalSourceEnvironment,
+                    ...agentSourceEnvironment,
+                    ...launchEnvironment
+                },
+                workspace: agentWorkspace,
+                profile: binding.config.profile,
+                trustWorkspace: true
+            })
+            : undefined;
+        if (codexConfig?.notify.status === "configured") {
+            throw new Error("Codex notify is already configured by "
+                + `${codexConfig.notify.source}; Yui requires exclusive ownership of the structured `
+                + "notify callback and refuses to replace or be replaced by native configuration.");
+        }
+        const managedRun = owner.scope === "task" && input.runId !== undefined
+            ? this.store.getAgentRun(owner.taskId, input.runId)
+            : null;
+        const roleConfig = binding.config.adapterId === "claude"
+            && owner.scope === "task"
+            && input.runId !== undefined
+            ? managedClaudeControlPlaneConfig(binding.config, owner.taskId, managedRun?.workItemId, input.runId, this.#controlPlane)
+            : binding.config;
+        const effectiveConfig = withNativeProjectDirectories(roleConfig, nativeAdditionalDirectories(effective.workspace, agentWorkspace));
         const compileInput = {
             agent,
-            config: binding.config,
-            workspace: role.workspace,
-            systemPrompt: role.systemPrompt
+            config: effectiveConfig,
+            workspace: agentWorkspace,
+            ...(sessionTitle === undefined ? {} : { sessionTitle }),
+            ...sessionContext,
+            ...(codexConfig === undefined
+                ? {}
+                : { codexDeveloperInstructions: codexConfig.developerInstructions })
         };
         if (input.mode === "resume"
             && knownNativeSessionId !== undefined
@@ -88,41 +313,280 @@ export class FileRoleLaunchPlanner {
         let session;
         if (binding.adapterId === "codex") {
             args = addCodexSessionNotify(args, launchMode, this.#cliPath);
+            // A fresh Codex TUI has no provider event before its first prompt. Carry
+            // the exact Run input as the provider's positional launch prompt so it is
+            // submitted only after Codex completes startup; never race terminal bytes
+            // and Enter against TUI initialization.
+            if (owner.scope === "task" && input.runId !== undefined) {
+                if (managedRun === null || managedRun.status !== "active") {
+                    throw new Error(`Managed Codex Run is no longer active: ${input.runId}.`);
+                }
+                args = addCodexLifecycleHooks(args, launchMode, this.#cliPath);
+                // End option parsing before the opaque prompt so a wakeup beginning
+                // with '-' can never be reinterpreted as a Codex CLI flag.
+                args.push("--", managedRun.input);
+            }
             session = launchMode === "resume"
-                ? readySession(input.agentId, binding.adapterId, resumeNativeSessionId)
+                ? readySession(input.agentId, binding.adapterId, resumeNativeSessionId, effective)
                 : null;
         }
         else if (launchMode === "new") {
-            const nativeSessionId = requireText(this.#createNativeSessionId(), "Native session id");
+            if (owner.scope === "task" && input.runId !== undefined) {
+                args.push("--plugin-dir", ensureManagedClaudeLifecyclePlugin(this.home, this.#cliPath));
+            }
+            const nativeSessionId = requireText(input.launchId === undefined
+                ? this.#createNativeSessionId()
+                : nativeSessionIdForLaunch(this.home, input.launchId, input.agentId, input.adapterId), "Native session id");
             args.push("--session-id", nativeSessionId);
-            session = readySession(input.agentId, binding.adapterId, nativeSessionId);
+            session = readySession(input.agentId, binding.adapterId, nativeSessionId, effective);
         }
         else {
-            session = readySession(input.agentId, binding.adapterId, resumeNativeSessionId);
+            if (owner.scope === "task" && input.runId !== undefined) {
+                args.push("--plugin-dir", ensureManagedClaudeLifecyclePlugin(this.home, this.#cliPath));
+            }
+            session = readySession(input.agentId, binding.adapterId, resumeNativeSessionId, effective);
+        }
+        const runtimeDescriptor = owner.scope === "task"
+            ? createExactTaskRuntimeDescriptor({
+                controlPlaneDigest: exactControlPlaneDigest(this.#controlPlane),
+                taskId: owner.taskId,
+                roleName: role.name,
+                agentId: configured.id,
+                adapterId: configured.adapterId,
+                workspace: effectiveWorkspace,
+                ...(input.runId === undefined ? {} : { runId: input.runId }),
+                ...(input.launchId === undefined ? {} : { launchId: input.launchId }),
+                ...(session === null
+                    ? {}
+                    : { nativeSessionId: session.nativeSessionId })
+            })
+            : undefined;
+        const runtimeDescriptorSource = runtimeDescriptor === undefined
+            ? undefined
+            : exactTaskRuntimeDescriptorPath(this.home, runtimeDescriptor);
+        if (runtimeDescriptor !== undefined && runtimeDescriptorSource !== undefined) {
+            writeTextFileAtomically(runtimeDescriptorSource, `${serializeExactDescriptor(runtimeDescriptor)}\n`);
         }
+        const launch = {
+            command: configured.command,
+            args,
+            env: {
+                ...launchEnvironment,
+                YUI_HOME: resolve(this.home),
+                YUI_SESSION_SCOPE: owner.scope,
+                ...(owner.scope === "task" ? { YUI_TASK_ID: owner.taskId } : {}),
+                YUI_ROLE: role.name,
+                YUI_AGENT_ID: configured.id,
+                YUI_ADAPTER_ID: configured.adapterId,
+                YUI_WORKSPACE: effectiveWorkspace,
+                ...(runtimeDescriptor === undefined
+                    ? {}
+                    : {
+                        [YUI_CONTROL_PLANE_DESCRIPTOR]: serializeExactDescriptor(this.#controlPlane),
+                        [YUI_TASK_RUNTIME_DESCRIPTOR]: runtimeDescriptorSource
+                    }),
+                ...(sessionTitle === undefined
+                    ? {}
+                    : {
+                        YUI_SESSION_TITLE: sessionTitle,
+                        ...(configured.adapterId === "codex"
+                            ? {
+                                YUI_AGENT_COMMAND: configured.command,
+                                YUI_AGENT_BASE_ARGS: JSON.stringify(configured.baseArgs)
+                            }
+                            : {})
+                    }),
+                ...(input.launchId === undefined
+                    ? {}
+                    : { YUI_LAUNCH_ID: input.launchId }),
+                ...(input.runId === undefined ? {} : { YUI_RUN_ID: input.runId }),
+                ...(session === null
+                    ? {}
+                    : { YUI_NATIVE_SESSION_ID: session.nativeSessionId })
+            }
+        };
+        const scopedLaunch = owner.scope === "task"
+            ? this.#applyWorkspaceScope(owner.taskId, role, launch, workspaceOverride)
+            : launch;
         return {
             role: {
                 name: role.name,
-                workspace: role.workspace,
+                workspace: effectiveWorkspace,
+                ...(agentWorkspace === effectiveWorkspace ? {} : { cwd: agentWorkspace }),
                 ...(owner.scope === "task" ? { status: role.status } : {})
             },
-            launch: {
-                command: configured.command,
-                args,
-                env: {
-                    ...resolveAgentEnvironment(agent, this.#environment),
-                    YUI_HOME: resolve(this.home),
-                    YUI_SESSION_SCOPE: owner.scope,
-                    ...(owner.scope === "task" ? { YUI_TASK_ID: owner.taskId } : {}),
-                    YUI_ROLE: role.name,
-                    YUI_AGENT_ID: configured.id,
-                    YUI_ADAPTER_ID: configured.adapterId,
-                    YUI_WORKSPACE: role.workspace
-                }
-            },
-            session
+            launch: scopedLaunch,
+            session,
+            ...(binding.adapterId === "codex" && input.runId !== undefined
+                ? { initialPromptRunId: input.runId }
+                : {})
+        };
+    }
+    #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
+                    ? this.store.getTaskWorkspace(taskId)
+                    : this.store.getWorkItemWorkspace(taskId, this.store.listWorkItems(taskId).find((item) => item.assignee === role.name && item.status === "running").id));
+        if (workspace === null || workspace === undefined)
+            return launch;
+        return {
+            ...launch,
+            env: {
+                ...workspaceScopeEnvironment(launch.env, workspace)
+            }
         };
     }
+    #selectConfiguredAgentEnvironment(source) {
+        const selected = {};
+        for (const agent of this.store.listConfiguredAgents()) {
+            for (const binding of agent.environment) {
+                const value = source[binding.sourceName];
+                if (value !== undefined)
+                    selected[binding.sourceName] = value;
+            }
+        }
+        return selected;
+    }
+    #selectConfiguredNativeEnvironment(source) {
+        const names = new Set(this.store.listConfiguredAgents().flatMap((agent) => (nativeAgentEnvironmentNames(agent.adapterId))));
+        return selectEnvironment(source, names);
+    }
+}
+function nativeAgentWorkspace(workspace) {
+    return workspace.entries.length === 1
+        ? workspace.entries[0].path
+        : workspace.root;
+}
+function nativeAdditionalDirectories(workspace, agentWorkspace) {
+    return [workspace.root, ...workspace.entries.map(({ path }) => path)]
+        .filter((path) => path !== agentWorkspace);
+}
+function withNativeProjectDirectories(config, projectDirectories) {
+    if (projectDirectories.length === 0)
+        return config;
+    return {
+        ...config,
+        additionalDirectories: [...new Set([
+                ...(config.additionalDirectories ?? []),
+                ...projectDirectories
+            ])]
+    };
+}
+function resolveTaskRoleEffectiveLaunch(store, role) {
+    const item = store.listWorkItems(role.taskId).find((candidate) => (candidate.assignee === role.name
+        && !["completed", "failed", "retired"].includes(candidate.status))) ?? null;
+    const workspace = (item === null
+        ? store.getTaskWorkspace(role.taskId)
+        : store.getWorkItemWorkspace(role.taskId, item.id))
+        ?? store.getTaskWorkspace(role.taskId)
+        ?? undefined;
+    return resolveEffectiveLaunch({
+        role,
+        purpose: "execution",
+        ...(workspace === undefined ? {} : { workspace }),
+        ...(item === null ? {} : { workItemWriteProjectIds: item.writeProjectIds })
+    });
+}
+function workspaceScopeEnvironment(environment, workspace) {
+    return {
+        ...environment,
+        YUI_WRITABLE_PROJECT_IDS: JSON.stringify(workspace.entries
+            .filter(({ access }) => access === "write")
+            .map(({ projectId }) => projectId)),
+        YUI_CONTEXT_PROJECT_IDS: JSON.stringify(workspace.entries
+            .filter(({ access }) => access === "read")
+            .map(({ projectId }) => projectId)),
+        YUI_WORKSPACE_PROJECTS: JSON.stringify(Object.fromEntries(workspace.entries.map(({ projectId, directory, access, path }) => [
+            projectId,
+            { directory, access, path }
+        ])))
+    };
+}
+function ensureManagedClaudeLifecyclePlugin(home, cliPath) {
+    const root = join(resolve(home), "runtime", "claude-lifecycle-plugin");
+    writeTextFileAtomically(join(root, ".claude-plugin", "plugin.json"), `${JSON.stringify({
+        name: "yui-runtime-lifecycle",
+        description: "Yui-owned exact Run lifecycle transport",
+        version: "1.0.0"
+    }, null, 2)}\n`);
+    const command = {
+        type: "command",
+        command: canonicalPath(process.execPath),
+        args: [canonicalPath(cliPath), "internal", "claude-hook"]
+    };
+    writeTextFileAtomically(join(root, "hooks", "hooks.json"), `${JSON.stringify({
+        hooks: {
+            // SessionStart proves the session exists (and, for source=startup,
+            // pre-input readiness); UserPromptSubmit is the exact provider-accepted
+            // fence; PostToolUse is a provider-native in-turn progress fact and
+            // StopFailure is the terminal failure fact. All route to the same
+            // Yui-owned entrypoint, which parses by hook_event_name.
+            SessionStart: [{ hooks: [command] }],
+            UserPromptSubmit: [{ hooks: [command] }],
+            PostToolUse: [{ hooks: [command] }],
+            StopFailure: [{ hooks: [command] }]
+        }
+    }, null, 2)}\n`);
+    return root;
+}
+function managedClaudeControlPlaneConfig(config, taskId, workItemId, runId, controlPlane) {
+    if (config.permission.strategy !== "configured")
+        return config;
+    const exact = exactControlPlaneCommandPrefix(controlPlane);
+    const managed = [
+        `Bash(${exact} --json task context ${taskId})`,
+        `Bash(${exact} --json task work list ${taskId})`,
+        ...(workItemId === undefined
+            ? []
+            : [`Bash(${exact} --json task work show ${workItemId})`]),
+        `Bash(${exact} task run yield ${runId} --summary-file -:*)`
+    ];
+    const existing = (config.permission.allowedTools ?? [])
+        .filter((rule) => !isManagedYuiBashRule(rule));
+    return {
+        ...config,
+        permission: {
+            ...config.permission,
+            allowedTools: [...new Set([...existing, ...managed])]
+        }
+    };
+}
+function isManagedYuiBashRule(rule) {
+    const normalized = rule.trim();
+    return /^Bash\(yui(?:\s|:\*|\*|\))/u.test(normalized)
+        || /^Bash\(.*\s--yui-control\s/u.test(normalized);
+}
+function renderExactControlPlaneInstructions(descriptor) {
+    const command = exactControlPlaneCommandPrefix(descriptor);
+    return [
+        "Exact Yui control-plane command prefix for this managed Task session:",
+        `\`${command}\``,
+        "Replace the portable bare `yui` token in Yui Role Skills and dispatch instructions with this exact prefix.",
+        "Bare `yui`, a PATH launcher, another checkout CLI, another YUI_HOME, or a changed schema/Controller identity is invalid and fails before Task state is read or written."
+    ].join("\n");
+}
+function canonicalPath(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
+function patchEnvironment(current, names, values) {
+    const next = { ...current };
+    for (const name of names)
+        delete next[name];
+    for (const [name, value] of Object.entries(values))
+        next[name] = value;
+    return next;
 }
 /**
  * Codex invokes this argv after each completed turn and appends one JSON
@@ -140,12 +604,43 @@ function addCodexSessionNotify(args, mode, cliPath) {
     }
     return [...args.slice(0, -2), ...managed, ...args.slice(-2)];
 }
-function readySession(agentId, adapterId, nativeSessionId) {
+/**
+ * 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 Run fence.
+ */
+function codexLifecycleHooksConfig(cliPath) {
+    const command = [
+        shellQuote(canonicalPath(process.execPath)),
+        shellQuote(canonicalPath(cliPath)),
+        "internal",
+        "codex-hook"
+    ].join(" ");
+    const handler = `{hooks=[{type="command",command=${JSON.stringify(command)}}]}`;
+    return `hooks={SessionStart=[${handler}],UserPromptSubmit=[${handler}]}`;
+}
+function addCodexLifecycleHooks(args, mode, cliPath) {
+    // Session flags are Yui-owned and exact to this launch. Hook trust bypass is
+    // still explicit because these handlers execute a local command.
+    const managed = [
+        "--enable", "hooks",
+        "--config", codexLifecycleHooksConfig(cliPath),
+        "--dangerously-bypass-hook-trust"
+    ];
+    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)];
+}
+function readySession(agentId, adapterId, nativeSessionId, effective) {
     return {
         agentId,
         adapterId,
         nativeSessionId: requireText(nativeSessionId, "Native session id"),
-        status: "ready"
+        status: "ready",
+        effective
     };
 }
 function requireText(value, label) {
@@ -154,3 +649,18 @@ function requireText(value, label) {
     }
     return value.trim();
 }
+function sameWorkspaceProjects(workspace, projectIds) {
+    const actual = workspace.entries.map(({ projectId }) => projectId).sort();
+    const expected = [...projectIds].sort();
+    return actual.length === expected.length
+        && actual.every((projectId, index) => projectId === expected[index]);
+}
+function sameWritableProjects(workspace, projectIds) {
+    const actual = workspace.entries
+        .filter(({ access }) => access === "write")
+        .map(({ projectId }) => projectId)
+        .sort();
+    const expected = [...projectIds].sort();
+    return actual.length === expected.length
+        && actual.every((projectId, index) => projectId === expected[index]);
+}