Function resolveWorkspaceRootPath

src/node/runtime/runtimeHelpers.ts:39–79

(
  metadata: WorkspaceMetadataForRuntime,
  runtime: Runtime
)

 * sub-project directory twice and miss the parent project's guidance entirely.
 */
export function resolveWorkspaceRootPath(
  metadata: WorkspaceMetadataForRuntime,
  runtime: Runtime
): string {
  if (metadata.projectPath === metadata.name) {
    // In-place workspaces (CLI/benchmarks) execute directly in their project root instead of a
    // named sibling checkout, so deriving a worktree path would be reconstructing the wrong shape.
    return metadata.projectPath;
  }

  const runtimeWorkspacePath = runtime.getWorkspacePath(metadata.projectPath, metadata.name);
  assert(runtimeWorkspacePath, `Workspace ${metadata.name} resolved to an empty runtime path`);

  if (isDockerRuntime(metadata.runtimeConfig)) {
    return runtimeWorkspacePath;
  }

  const persistedWorkspacePath = metadata.namedWorkspacePath?.trim();
  if (!persistedWorkspacePath) {
    // SSH workspaces must keep using the persisted checkout root from config so upgraded legacy
    // workspaces do not silently fall back to the reconstructed hashed path and miss their real cwd.
    assert(
      !isSSHRuntime(metadata.runtimeConfig),
      `SSH workspace ${metadata.name} is missing a persisted workspace path`
    );

    // Other runtimes can still fall back to their canonical derived path when only identity metadata
    // is available (for example in narrow unit tests).
    return runtimeWorkspacePath;
  }

  if (isLocalProjectRuntime(metadata.runtimeConfig)) {
    // Project-dir local runtimes always execute directly in the project root.
    assert(
      persistedWorkspacePath === runtimeWorkspacePath,
      `Project-dir local workspace ${metadata.name} path mismatch: persisted=${persistedWorkspacePath} runtime=${runtimeWorkspacePath}`
    );
  }

  return persistedWorkspacePath;
}

/**
 * Append `metadata.subProjectPath` (if any) to a workspace root path, using the