@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.2

package/dist/builtin/workflows/src/extension/atomic-stage-session.ts

@@ -0,0 +1,186 @@
+import { basename } from "node:path";
+import type {
+  CreateAgentSessionOptions,
+  DefaultResourceLoaderInheritanceSnapshot,
+  PackageSource,
+} from "@bastani/atomic";
+import type { StageSessionRuntime } from "../runs/foreground/stage-runner.js";
+
+export interface PiSdkSettingsManager {
+  getCodexFastModeSettings(): { readonly chat: boolean; readonly workflow: boolean };
+}
+
+export interface PiSdkResourceLoader {
+  reload(): Promise<void>;
+}
+
+interface PiSdkSessionManager {
+  getCwd(): string;
+}
+
+export interface PiCodingAgentSdk {
+  getAgentDir(): string;
+  getBuiltinPackagePaths?: () => string[];
+  SettingsManager: {
+    create(cwd?: string, agentDir?: string, options?: { projectTrusted?: boolean }): PiSdkSettingsManager;
+  };
+  DefaultResourceLoader: new (options: {
+    cwd: string;
+    agentDir: string;
+    settingsManager?: PiSdkSettingsManager;
+    builtinPackagePaths?: PackageSource[];
+    resourceLoaderInheritanceSnapshot?: DefaultResourceLoaderInheritanceSnapshot;
+  }) => PiSdkResourceLoader;
+  createAgentSession(options?: AtomicCreateAgentSessionOptions): Promise<{ session: StageSessionRuntime }>;
+}
+
+export type AtomicCreateAgentSessionOptions = Omit<CreateAgentSessionOptions, "settingsManager" | "resourceLoader" | "sessionManager"> & {
+  settingsManager?: PiSdkSettingsManager;
+  resourceLoader?: PiSdkResourceLoader;
+  sessionManager?: PiSdkSessionManager;
+};
+
+export interface PrepareAtomicStageSessionOptions {
+  resourceLoaderInheritanceSnapshot?: DefaultResourceLoaderInheritanceSnapshot;
+}
+
+function resolveSessionCwd(options: AtomicCreateAgentSessionOptions | undefined): string {
+  return options?.cwd ?? options?.sessionManager?.getCwd() ?? process.cwd();
+}
+
+/**
+ * Prepare Atomic SDK stage-session options with Atomic-first resource loading.
+ *
+ * The Atomic SDK's documented defaults are intentionally significant:
+ * omitted `agentDir` means credentials/models/settings can be read from the
+ * primary `~/.atomic/agent` paths first while still considering legacy
+ * `~/.pi/agent` compatibility paths when the SDK supports multiple config
+ * directories. Passing the computed default back as an explicit `agentDir`
+ * would accidentally turn that multi-dir behavior into a single-dir override.
+ *
+ * A user-supplied `agentDir` is still preserved exactly and remains an
+ * explicit override. A user-supplied `resourceLoader` is also preserved; in
+ * that case cwd/agentDir no longer control resource discovery and only affect
+ * session naming/tool path resolution, matching the pi SDK docs.
+ */
+export async function prepareAtomicStageSessionOptions(
+  options: CreateAgentSessionOptions | undefined,
+  sdk: PiCodingAgentSdk,
+  prepareOptions: PrepareAtomicStageSessionOptions = {},
+): Promise<AtomicCreateAgentSessionOptions | undefined> {
+  const atomicOptions = options as AtomicCreateAgentSessionOptions | undefined;
+  if (atomicOptions?.resourceLoader !== undefined) return atomicOptions;
+
+  const inheritanceSnapshot = prepareOptions.resourceLoaderInheritanceSnapshot;
+  const cwd = resolveSessionCwd(atomicOptions);
+  const hasAgentDirOverride = atomicOptions?.agentDir !== undefined;
+  const agentDir = atomicOptions?.agentDir ?? sdk.getAgentDir();
+  const settingsManager =
+    atomicOptions?.settingsManager ?? sdk.SettingsManager.create(
+      cwd,
+      agentDir,
+      inheritanceSnapshot?.projectTrusted === undefined
+        ? undefined
+        : { projectTrusted: inheritanceSnapshot.projectTrusted },
+    );
+  const inheritedBuiltinPackagePaths = inheritanceSnapshot?.builtinPackagePaths;
+  const builtinPackagePaths = inheritedBuiltinPackagePaths === undefined
+    ? sdk.getBuiltinPackagePaths?.() ?? []
+    : [...inheritedBuiltinPackagePaths];
+  const resourceLoader = new sdk.DefaultResourceLoader({
+    cwd,
+    agentDir,
+    settingsManager,
+    resourceLoaderInheritanceSnapshot: inheritanceSnapshot,
+    builtinPackagePaths: stageBuiltinPackagePaths(builtinPackagePaths),
+  });
+  await reloadWorkflowStageResources(resourceLoader);
+
+  return {
+    ...atomicOptions,
+    cwd,
+    ...(hasAgentDirOverride ? { agentDir } : {}),
+    settingsManager,
+    resourceLoader,
+  };
+}
+
+function clonePackageSource(source: PackageSource): PackageSource {
+  if (typeof source === "string") return source;
+  return {
+    source: source.source,
+    ...(source.extensions === undefined ? {} : { extensions: [...source.extensions] }),
+    ...(source.skills === undefined ? {} : { skills: [...source.skills] }),
+    ...(source.prompts === undefined ? {} : { prompts: [...source.prompts] }),
+    ...(source.themes === undefined ? {} : { themes: [...source.themes] }),
+    ...(source.workflows === undefined ? {} : { workflows: [...source.workflows] }),
+  };
+}
+
+function packageSourcePath(source: PackageSource): string {
+  return typeof source === "string" ? source : source.source;
+}
+
+function disablePackageExtensions(source: PackageSource): PackageSource {
+  if (typeof source === "string") return { source, extensions: [] };
+  return { ...source, extensions: [] };
+}
+
+function stageBuiltinPackagePaths(paths: readonly PackageSource[]): PackageSource[] {
+  // Workflow stages are child AgentSessions owned by the workflow extension.
+  // Loading the workflows extension again inside that child session replays its
+  // `session_start` lifecycle and clears/kills the parent workflow store. Keep
+  // the workflows package itself so its bundled skills/prompts/resources remain
+  // available, but disable only its extension entry for stage sessions.
+  return paths.map((path) => {
+    const cloned = clonePackageSource(path);
+    return basename(packageSourcePath(cloned)) === "workflows"
+      ? disablePackageExtensions(cloned)
+      : cloned;
+  });
+}
+
+const SUBAGENT_CHILD_EXTENSION_ENV_KEYS = [
+  "ATOMIC_SUBAGENT_CHILD",
+  "ATOMIC_SUBAGENT_FANOUT_CHILD",
+  "PI_SUBAGENT_CHILD",
+  "PI_SUBAGENT_FANOUT_CHILD",
+] as const;
+
+let workflowStageResourceReloadQueue: Promise<void> = Promise.resolve();
+
+async function reloadWorkflowStageResources(resourceLoader: PiSdkResourceLoader): Promise<void> {
+  const queuedReload = workflowStageResourceReloadQueue.then(() =>
+    reloadWorkflowStageResourcesWithEnvIsolation(resourceLoader),
+  );
+  workflowStageResourceReloadQueue = queuedReload.catch(() => undefined);
+  return queuedReload;
+}
+
+async function reloadWorkflowStageResourcesWithEnvIsolation(resourceLoader: PiSdkResourceLoader): Promise<void> {
+  // Workflow stage sessions are already governed by an orchestration context
+  // that disables recursive workflow tools and caps nested subagent depth. When
+  // a workflow itself runs inside a subagent child process, inherited subagent
+  // child env flags would otherwise make the bundled subagents extension skip
+  // registering its `subagent` tool before the stage session exists. Isolate
+  // extension discovery from those parent-process flags so an explicit
+  // `tools: ["subagent"]` allowlist works the same in workflow stages everywhere.
+  // The isolation mutates process-global env, so serialize the full
+  // save/delete/reload/restore section. Without this queue, overlapping workflow
+  // stage session creation can snapshot an already-cleared env and restore that
+  // stale snapshot after another reload restores the real parent values.
+  const previousValues = new Map<string, string | undefined>();
+  for (const key of SUBAGENT_CHILD_EXTENSION_ENV_KEYS) {
+    previousValues.set(key, process.env[key]);
+    delete process.env[key];
+  }
+  try {
+    await resourceLoader.reload();
+  } finally {
+    for (const key of SUBAGENT_CHILD_EXTENSION_ENV_KEYS) {
+      const previousValue = previousValues.get(key);
+      if (previousValue === undefined) delete process.env[key];
+      else process.env[key] = previousValue;
+    }
+  }
+}

package/dist/builtin/workflows/src/extension/config-file-loader.ts

@@ -0,0 +1,152 @@
+import {
+  WORKFLOW_LIFECYCLE_NOTICE_KINDS,
+  type WorkflowLifecycleNoticeKind,
+} from "./lifecycle-notifications.js";
+import type { ConfigDiagnostic, WorkflowExtensionConfig } from "./config-loader.js";
+
+const WORKFLOW_LIFECYCLE_NOTICE_KIND_SET = new Set<string>(WORKFLOW_LIFECYCLE_NOTICE_KINDS);
+
+async function tryReadFile(filePath: string): Promise<string | null> {
+  const { readFile } = await import("node:fs/promises");
+  try {
+    return await readFile(filePath, "utf-8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+function isWorkflowLifecycleNoticeKind(value: unknown): value is WorkflowLifecycleNoticeKind {
+  return typeof value === "string" && WORKFLOW_LIFECYCLE_NOTICE_KIND_SET.has(value);
+}
+
+function validateConfig(value: unknown): string | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return "config must be a JSON object";
+  }
+  const c = value as Record<string, unknown>;
+
+  if ("maxDepth" in c && (typeof c["maxDepth"] !== "number" || !Number.isInteger(c["maxDepth"]) || (c["maxDepth"] as number) < 0)) {
+    return `"maxDepth" must be a non-negative integer, got ${JSON.stringify(c["maxDepth"])}`;
+  }
+
+  if ("defaultConcurrency" in c && (typeof c["defaultConcurrency"] !== "number" || !Number.isInteger(c["defaultConcurrency"]) || (c["defaultConcurrency"] as number) < 1)) {
+    return `"defaultConcurrency" must be a positive integer, got ${JSON.stringify(c["defaultConcurrency"])}`;
+  }
+
+  if ("persistRuns" in c && typeof c["persistRuns"] !== "boolean") {
+    return `"persistRuns" must be a boolean, got ${JSON.stringify(c["persistRuns"])}`;
+  }
+
+  if ("statusFile" in c && typeof c["statusFile"] !== "boolean") {
+    return `"statusFile" must be a boolean, got ${JSON.stringify(c["statusFile"])}`;
+  }
+
+  if ("resumeInFlight" in c) {
+    const v = c["resumeInFlight"];
+    if (v !== "ask" && v !== "auto" && v !== "never") {
+      return `"resumeInFlight" must be "ask", "auto", or "never", got ${JSON.stringify(v)}`;
+    }
+  }
+
+  if ("workflowNotifications" in c) {
+    const value = c["workflowNotifications"];
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      return `"workflowNotifications" must be a JSON object, got ${JSON.stringify(typeof value)}`;
+    }
+    const notifications = value as Record<string, unknown>;
+    if ("enabled" in notifications && typeof notifications["enabled"] !== "boolean") {
+      return `"workflowNotifications.enabled" must be a boolean, got ${JSON.stringify(notifications["enabled"])}`;
+    }
+    if ("notifyOn" in notifications) {
+      const notifyOn = notifications["notifyOn"];
+      if (!Array.isArray(notifyOn)) {
+        return `"workflowNotifications.notifyOn" must be an array, got ${JSON.stringify(typeof notifyOn)}`;
+      }
+      if (notifyOn.length === 0) {
+        return `"workflowNotifications.notifyOn" must be a non-empty array`;
+      }
+      for (const item of notifyOn) {
+        if (!isWorkflowLifecycleNoticeKind(item)) {
+          return `"workflowNotifications.notifyOn" entries must be "completed", "failed", or "awaiting_input", got ${JSON.stringify(item)}`;
+        }
+      }
+    }
+  }
+
+  if ("workflows" in c) {
+    if (c["workflows"] === null || typeof c["workflows"] !== "object" || Array.isArray(c["workflows"])) {
+      return `"workflows" must be a JSON object, got ${JSON.stringify(typeof c["workflows"])}`;
+    }
+    const wf = c["workflows"] as Record<string, unknown>;
+    for (const [name, entry] of Object.entries(wf)) {
+      if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+        return `"workflows.${name}" must be an object with a "path" field`;
+      }
+      const e = entry as Record<string, unknown>;
+      if (typeof e["path"] !== "string" || (e["path"] as string).trim().length === 0) {
+        return `"workflows.${name}.path" must be a non-empty string, got ${JSON.stringify(e["path"])}`;
+      }
+    }
+  }
+
+  return null;
+}
+
+export type LoadFileOutcome =
+  | { kind: "missing" }
+  | { kind: "ok"; parsed: WorkflowExtensionConfig }
+  | { kind: "error"; diagnostic: ConfigDiagnostic };
+
+export async function loadConfigFile(filePath: string): Promise<LoadFileOutcome> {
+  let text: string | null;
+  try {
+    text = await tryReadFile(filePath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      kind: "error",
+      diagnostic: {
+        level: "error",
+        code: "CONFIG_INVALID",
+        message: `Failed to read config file: ${msg}`,
+        source: filePath,
+      },
+    };
+  }
+
+  if (text === null) {
+    return { kind: "missing" };
+  }
+
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      kind: "error",
+      diagnostic: {
+        level: "error",
+        code: "CONFIG_INVALID",
+        message: `Invalid JSON in config file: ${msg}`,
+        source: filePath,
+      },
+    };
+  }
+
+  const reason = validateConfig(value);
+  if (reason !== null) {
+    return {
+      kind: "error",
+      diagnostic: {
+        level: "error",
+        code: "CONFIG_INVALID",
+        message: `Invalid config shape: ${reason}`,
+        source: filePath,
+      },
+    };
+  }
+
+  return { kind: "ok", parsed: value as WorkflowExtensionConfig };
+}

package/dist/builtin/workflows/src/extension/config-loader.ts

@@ -19,12 +19,8 @@
 import { join, isAbsolute } from "node:path";
 import { homedir } from "node:os";
 import { CONFIG_DIR_NAME, CONFIG_DIR_NAMES, getProjectConfigPaths } from "@bastani/atomic";
-import {
-  WORKFLOW_LIFECYCLE_NOTICE_KINDS,
-  type WorkflowLifecycleNoticeKind,
-} from "./lifecycle-notifications.js";
-
-const WORKFLOW_LIFECYCLE_NOTICE_KIND_SET = new Set<string>(WORKFLOW_LIFECYCLE_NOTICE_KINDS);
+import type { WorkflowLifecycleNoticeKind } from "./lifecycle-notifications.js";
+import { loadConfigFile } from "./config-file-loader.js";
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -122,167 +118,6 @@ export interface LoadWorkflowConfigOpts {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Attempt to read a file as text.
- * Returns the text content, or null if the file does not exist.
- * Throws on unexpected I/O errors.
- */
-async function tryReadFile(filePath: string): Promise<string | null> {
-  const { readFile } = await import("node:fs/promises");
-  try {
-    return await readFile(filePath, "utf-8");
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw err;
-  }
-}
-
-/**
- * Validate a parsed JSON value as a WorkflowExtensionConfig.
- * Returns null when valid, or a human-readable rejection reason.
- */
-function isWorkflowLifecycleNoticeKind(value: unknown): value is WorkflowLifecycleNoticeKind {
-  return typeof value === "string" && WORKFLOW_LIFECYCLE_NOTICE_KIND_SET.has(value);
-}
-
-function validateConfig(value: unknown): string | null {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    return "config must be a JSON object";
-  }
-  const c = value as Record<string, unknown>;
-
-  if ("maxDepth" in c && (typeof c["maxDepth"] !== "number" || !Number.isInteger(c["maxDepth"]) || (c["maxDepth"] as number) < 0)) {
-    return `"maxDepth" must be a non-negative integer, got ${JSON.stringify(c["maxDepth"])}`;
-  }
-
-  if ("defaultConcurrency" in c && (typeof c["defaultConcurrency"] !== "number" || !Number.isInteger(c["defaultConcurrency"]) || (c["defaultConcurrency"] as number) < 1)) {
-    return `"defaultConcurrency" must be a positive integer, got ${JSON.stringify(c["defaultConcurrency"])}`;
-  }
-
-  if ("persistRuns" in c && typeof c["persistRuns"] !== "boolean") {
-    return `"persistRuns" must be a boolean, got ${JSON.stringify(c["persistRuns"])}`;
-  }
-
-  if ("statusFile" in c && typeof c["statusFile"] !== "boolean") {
-    return `"statusFile" must be a boolean, got ${JSON.stringify(c["statusFile"])}`;
-  }
-
-  if ("resumeInFlight" in c) {
-    const v = c["resumeInFlight"];
-    if (v !== "ask" && v !== "auto" && v !== "never") {
-      return `"resumeInFlight" must be "ask", "auto", or "never", got ${JSON.stringify(v)}`;
-    }
-  }
-
-  if ("workflowNotifications" in c) {
-    const value = c["workflowNotifications"];
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-      return `"workflowNotifications" must be a JSON object, got ${JSON.stringify(typeof value)}`;
-    }
-    const notifications = value as Record<string, unknown>;
-    if ("enabled" in notifications && typeof notifications["enabled"] !== "boolean") {
-      return `"workflowNotifications.enabled" must be a boolean, got ${JSON.stringify(notifications["enabled"])}`;
-    }
-    if ("notifyOn" in notifications) {
-      const notifyOn = notifications["notifyOn"];
-      if (!Array.isArray(notifyOn)) {
-        return `"workflowNotifications.notifyOn" must be an array, got ${JSON.stringify(typeof notifyOn)}`;
-      }
-      if (notifyOn.length === 0) {
-        return `"workflowNotifications.notifyOn" must be a non-empty array`;
-      }
-      for (const item of notifyOn) {
-        if (!isWorkflowLifecycleNoticeKind(item)) {
-          return `"workflowNotifications.notifyOn" entries must be "completed", "failed", or "awaiting_input", got ${JSON.stringify(item)}`;
-        }
-      }
-    }
-  }
-
-  if ("workflows" in c) {
-    if (c["workflows"] === null || typeof c["workflows"] !== "object" || Array.isArray(c["workflows"])) {
-      return `"workflows" must be a JSON object, got ${JSON.stringify(typeof c["workflows"])}`;
-    }
-    const wf = c["workflows"] as Record<string, unknown>;
-    for (const [name, entry] of Object.entries(wf)) {
-      if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
-        return `"workflows.${name}" must be an object with a "path" field`;
-      }
-      const e = entry as Record<string, unknown>;
-      if (typeof e["path"] !== "string" || (e["path"] as string).trim().length === 0) {
-        return `"workflows.${name}.path" must be a non-empty string, got ${JSON.stringify(e["path"])}`;
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * Parse and validate a config file at the given path.
- * Returns one of three outcomes:
- *   { kind: "missing" }               — file doesn't exist; silently skip
- *   { kind: "ok"; parsed }            — file valid
- *   { kind: "error"; diagnostic }     — file invalid; emit diagnostic
- */
-type LoadFileOutcome =
-  | { kind: "missing" }
-  | { kind: "ok"; parsed: WorkflowExtensionConfig }
-  | { kind: "error"; diagnostic: ConfigDiagnostic };
-
-async function loadConfigFile(filePath: string): Promise<LoadFileOutcome> {
-  let text: string | null;
-  try {
-    text = await tryReadFile(filePath);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return {
-      kind: "error",
-      diagnostic: {
-        level: "error",
-        code: "CONFIG_INVALID",
-        message: `Failed to read config file: ${msg}`,
-        source: filePath,
-      },
-    };
-  }
-
-  if (text === null) {
-    return { kind: "missing" };
-  }
-
-  let value: unknown;
-  try {
-    value = JSON.parse(text);
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return {
-      kind: "error",
-      diagnostic: {
-        level: "error",
-        code: "CONFIG_INVALID",
-        message: `Invalid JSON in config file: ${msg}`,
-        source: filePath,
-      },
-    };
-  }
-
-  const reason = validateConfig(value);
-  if (reason !== null) {
-    return {
-      kind: "error",
-      diagnostic: {
-        level: "error",
-        code: "CONFIG_INVALID",
-        message: `Invalid config shape: ${reason}`,
-        source: filePath,
-      },
-    };
-  }
-
-  return { kind: "ok", parsed: value as WorkflowExtensionConfig };
-}
-
 /**
  * Merge two configs: `override` values win over `base`.
  * The `workflows` map is merged key-by-key (override wins on conflict).

package/dist/builtin/workflows/src/extension/discovery-loaders.ts

@@ -0,0 +1,115 @@
+import { readdir, stat } from "node:fs/promises";
+import { extname, isAbsolute, join, resolve } from "node:path";
+import type { DiscoveryDiagnostic, DiscoveryKind } from "./discovery.js";
+import {
+  collectWorkflowModuleCandidates,
+  loadWorkflowModule,
+} from "./workflow-module-loader.js";
+
+export type WorkflowModuleCandidateRecord = {
+  readonly value: unknown;
+  readonly exportKey: string;
+  readonly kind: DiscoveryKind;
+  readonly filePath?: string;
+  readonly configuredName?: string;
+};
+
+/** Scan a directory for .ts/.js/.mjs/.cjs files, returning sorted absolute paths. */
+async function scanWorkflowDir(dir: string): Promise<string[] | null> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const WORKFLOW_EXTS = new Set([".ts", ".js", ".mjs", ".cjs"]);
+    return entries
+      .filter((e) => e.isFile() && WORKFLOW_EXTS.has(extname(e.name)))
+      .map((e) => join(dir, e.name))
+      .sort();
+  } catch {
+    // Directory doesn't exist or isn't readable — not an error, just empty
+    return null;
+  }
+}
+
+async function importWorkflowFile(
+  filePath: string,
+  kind: DiscoveryKind,
+  diagnostics: DiscoveryDiagnostic[],
+): Promise<WorkflowModuleCandidateRecord[]> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = loadWorkflowModule(filePath);
+  } catch (err) {
+    diagnostics.push({
+      level: "error",
+      code: "IMPORT_FAILED",
+      message: `Failed to import "${filePath}": ${err instanceof Error ? err.message : String(err)}`,
+      source: filePath,
+    });
+    return [];
+  }
+
+  return collectWorkflowModuleCandidates(mod).map((candidate) => ({
+    ...candidate,
+    kind,
+    filePath,
+  }));
+}
+
+/** Load workflows from a scanned directory. */
+export async function loadFromDir(
+  dir: string,
+  kind: DiscoveryKind,
+  diagnostics: DiscoveryDiagnostic[],
+): Promise<WorkflowModuleCandidateRecord[]> {
+  const files = await scanWorkflowDir(dir);
+  if (files === null) return [];
+
+  const all: WorkflowModuleCandidateRecord[] = [];
+  for (const filePath of files) {
+    const candidates = await importWorkflowFile(filePath, kind, diagnostics);
+    all.push(...candidates);
+  }
+  return all;
+}
+
+/** Load workflows from an explicit path list (from config). */
+export async function loadFromPaths(
+  pathsOrMap: string[] | Record<string, string>,
+  kind: DiscoveryKind,
+  baseCwd: string,
+  diagnostics: DiscoveryDiagnostic[],
+): Promise<WorkflowModuleCandidateRecord[]> {
+  const all: WorkflowModuleCandidateRecord[] = [];
+
+  const entries: Array<{ rawPath: string; configuredName?: string }> = Array.isArray(pathsOrMap)
+    ? pathsOrMap.map((p) => ({ rawPath: p }))
+    : Object.entries(pathsOrMap).map(([name, p]) => ({ rawPath: p, configuredName: name }));
+
+  for (const { rawPath, configuredName } of entries) {
+    const absPath = isAbsolute(rawPath) ? rawPath : resolve(baseCwd, rawPath);
+
+    let pathStats: Awaited<ReturnType<typeof stat>> | undefined;
+    try {
+      pathStats = await stat(absPath);
+    } catch {
+      pathStats = undefined;
+    }
+
+    if (pathStats === undefined) {
+      diagnostics.push({
+        level: "error",
+        code: "PATH_NOT_FOUND",
+        message: `Workflow path not found: "${absPath}"`,
+        source: absPath,
+      });
+      continue;
+    }
+
+    const candidates = pathStats.isDirectory()
+      ? await loadFromDir(absPath, kind, diagnostics)
+      : await importWorkflowFile(absPath, kind, diagnostics);
+    for (const c of candidates) {
+      all.push({ ...c, ...(configuredName !== undefined ? { configuredName } : {}) });
+    }
+  }
+  return all;
+}