Method create

src/node/services/terminalService.ts:110–304

(params: TerminalCreateParams)

  }

  async create(params: TerminalCreateParams): Promise<TerminalSession> {
    try {
      // 1. Resolve workspace
      const allMetadata = await this.config.getAllWorkspaceMetadata();
      const workspaceMetadata = allMetadata.find((w) => w.id === params.workspaceId);

      if (!workspaceMetadata) {
        throw new Error(`Workspace not found: ${params.workspaceId}`);
      }

      // Validate required fields before proceeding - projectPath is required for project-dir runtimes
      if (!workspaceMetadata.projectPath) {
        log.error("Workspace metadata missing projectPath", {
          workspaceId: params.workspaceId,
          name: workspaceMetadata.name,
          runtimeConfig: workspaceMetadata.runtimeConfig,
          projectName: workspaceMetadata.projectName,
          metadata: JSON.stringify(workspaceMetadata),
        });
        throw new Error(
          `Workspace "${workspaceMetadata.name}" (${params.workspaceId}) is missing projectPath. ` +
            `This may indicate a corrupted config or a workspace that was not properly associated with a project.`
        );
      }

      // 2. Create runtime (pass workspace info for Docker container name derivation)
      const runtime = createRuntimeForWorkspace(workspaceMetadata);

      // 3. Use the persisted workspace root everywhere users can observe it, except for runtimes
      // like Docker whose executable cwd is intentionally translated inside the runtime.
      const workspacePath = resolveWorkspaceExecutionPath(workspaceMetadata, runtime);

      // Keep integrated terminal context aligned with the bash tool for stable workspace metadata.
      // We intentionally skip dynamic values (like cost/model) because long-lived shells would go stale.
      const runtimeType = getRuntimeType(workspaceMetadata.runtimeConfig);
      const shouldInjectLocalEnv = runtimeType === "local" || runtimeType === "worktree";
      const muxEnv = shouldInjectLocalEnv
        ? getMuxEnv(workspaceMetadata.projectPath, runtimeType, workspaceMetadata.name, {
            workspaceId: workspaceMetadata.id,
          })
        : undefined;

      // Secrets are local/worktree only. Remote/docker-style transports would expose env via command args
      // unless we add a dedicated secure propagation path.
      const secrets = shouldInjectLocalEnv
        ? await secretsToRecord(
            this.config.getEffectiveSecrets(workspaceMetadata.projectPath),
            this.opResolver
          )
        : {};

      // Any process launched from this terminal inherits these variables.
      // Proxy URI propagation allows terminal tools to construct externally reachable links.
      // MUX_PROXY_URI explicitly overrides VSCODE_PROXY_URI, and falls back to it when unset.
      const terminalEnv = muxEnv ? { ...muxEnv, ...this.getProxyUriEnv(), ...secrets } : undefined;

      // 4. Setup emitters and buffer
      // We don't know the sessionId yet (PTYService generates it), but PTYService uses a callback.