@yaag/cli 0.7.0 → 0.8.0

package/README.md

@@ -0,0 +1,31 @@
+# @yaag/cli
+
+The `yaag` CLI. It runs an Orchestration Program on Bun, describes one, and
+prepares a workspace for authoring.
+
+## Install
+
+```bash
+bun add @yaag/cli
+```
+
+The CLI needs Bun. Install Bun with `curl -fsSL https://bun.sh/install | bash`.
+
+## Commands
+
+- `yaag run <program.ts>` — run an Orchestration Program. `--args <json>`,
+  `--record <file>`, `--resume <file>`, `--replay <file>`, `--quiet`.
+- `yaag describe <program.ts>` — report the name, description, and args schema.
+- `yaag setup-workspace [dir]` — create `.yaag/` with the editor types.
+
+`yaag` with no valid command prints its usage text and exits with code 2.
+
+## Docs
+
+The full doc set ships with `@yaag/extension`:
+
+- [`getting-started.md`](../../packages/extension/docs/getting-started.md)
+- [`authoring.md`](../../packages/extension/docs/authoring.md)
+- [`examples.md`](../../packages/extension/docs/examples.md)
+- [`cli.md`](../../packages/extension/docs/cli.md)
+- [`troubleshooting.md`](../../packages/extension/docs/troubleshooting.md)

package/assets/types/runtime/agent/define-agent.d.ts

@@ -33,6 +33,13 @@ export interface AgentConfig {
     readonly skills?: readonly string[];
     /** Deny-list of skill names, applied after `skills`. */
     readonly disallowedSkills?: readonly string[];
+    /**
+     * Load the Effective Config's `agents.extensions` for Agents of this
+     * definition. Default true. A spawn's own `SpawnOptions.configExtensions`
+     * wins over this value; spawn *overrides* stay topology-only, so the opt-out
+     * is not one of them (ADR-0019, ADR-0040).
+     */
+    readonly configExtensions?: boolean;
     /** Ask options applied to every Ask on this Agent unless overridden per call. */
     readonly askDefaults?: AskOptions;
 }

package/assets/types/runtime/agent/spawn-extensions.d.ts

@@ -0,0 +1,39 @@
+import type { ConfigExtension } from "../config/index.ts";
+/** Everything one spawn needs to turn declarations into `-e` arguments. */
+export interface SpawnExtensionRequest {
+    /** Effective Config entries in merge order: global → project → run (spec rule 3). */
+    readonly configExtensions: readonly ConfigExtension[];
+    /** `SpawnOptions.extensions`, resolved against the program file as before. */
+    readonly declared?: readonly string[] | undefined;
+    /** False when the spawn or its definition opted out (spec rule 7). */
+    readonly useConfigExtensions: boolean;
+    /** Orchestration Program source path, the base of a relative spawn declaration. */
+    readonly programFile?: string | undefined;
+    /** Agent working directory, the project install root for `npm:`/`git:`. */
+    readonly projectRoot: string;
+}
+/** The two projections of one Agent's extensions: what launches, and what identifies. */
+export interface SpawnExtensions {
+    /** Absolute launch-ready `-e` arguments, deduplicated, in final order. */
+    readonly resolvedPaths: readonly string[];
+    /** The surviving declarations behind them, same order, unresolved (ADR-0040). */
+    readonly declared: readonly string[];
+}
+/**
+ * Resolves the extensions of one Agent: config-sourced first, spawn-declared
+ * last, deduplicated by resolved path with the first occurrence keeping its
+ * place. Returns undefined when nothing is declared at all, so an
+ * extension-free spawn keeps its request shape.
+ *
+ * The two bases are deliberately different: a relative *path* from a config
+ * file resolves against that file's directory, while an `npm:`/`git:`
+ * specifier still installs from the Agent working directory (`projectRoot`).
+ * An uninstalled specifier passes through verbatim and dedups by its literal
+ * string.
+ *
+ * A declaration joins `declared` only when it contributed at least one new
+ * resolved path, so the identity list describes what actually ran. Two
+ * different declarations that resolve to the same path therefore keep only the
+ * first, which is machine-dependent by nature of the resolution itself.
+ */
+export declare function resolveSpawnExtensions(request: SpawnExtensionRequest): Promise<SpawnExtensions | undefined>;

package/assets/types/runtime/agent/spawn-request.d.ts

@@ -7,6 +7,7 @@ export interface OpenRequestOptions {
     readonly cwd: string;
     readonly spawnOptions: SpawnOptions;
     readonly resolvedExtensionPaths?: readonly string[];
+    readonly declaredExtensions?: readonly string[];
     readonly sessionDir: string | undefined;
 }
 /**

package/assets/types/runtime/agent/spawn.d.ts

@@ -1,3 +1,4 @@
+import type { ConfigExtension } from "../config/index.ts";
 import type { EventSink } from "../events.ts";
 import type { RunContext } from "../run/index.ts";
 import type { TransportFactory } from "../transport/index.ts";
@@ -9,6 +10,8 @@ export interface SpawnDependencies {
     readonly emit: EventSink;
     readonly sessionDir: string | undefined;
     readonly programFile: string | undefined;
+    /** Effective Config entries, in merge order; empty when the Run has no config. */
+    readonly configExtensions: readonly ConfigExtension[];
 }
 /** A RunContext spawn function that can synchronously stop accepting new Agents. */
 export interface SpawnGate {

package/assets/types/runtime/cassette/cassette-schema.d.ts

@@ -30,6 +30,7 @@ export declare const CassetteSchema: Type.TObject<{
             name: Type.TString;
             cwd: Type.TString;
             worktree: Type.TOptional<Type.TLiteral<true>>;
+            declaredExtensions: Type.TOptional<Type.TArray<Type.TString>>;
         }>;
         model: Type.TString;
         sessionFile: Type.TOptional<Type.TString>;

package/assets/types/runtime/cassette/cassette.d.ts

@@ -67,6 +67,11 @@ export interface CassetteSpawn {
     readonly disallowedSkills?: readonly string[];
     /** Deterministic request, present only when the Agent requested a worktree. */
     readonly worktree?: true;
+    /**
+     * Declared extensions in declaration order, unresolved so a Cassette matches
+     * across machines (ADR-0040). Absent when the Agent ran no extension.
+     */
+    readonly declaredExtensions?: readonly string[];
 }
 /** The frames attributed to one Ask marker. */
 export interface CassetteAsk {

package/assets/types/runtime/config/config-file.d.ts

@@ -0,0 +1,22 @@
+import { type YaagConfigDocument } from "./config-schema.ts";
+/** One config file that contributed to the Effective Config. */
+export interface ConfigLayer {
+    /** The file this layer was read from. */
+    readonly file: string;
+    /** The file's own directory: relative paths inside it resolve here (spec rule 4). */
+    readonly directory: string;
+    readonly document: YaagConfigDocument;
+}
+/** Whether an absent file is an empty layer or a Run-start failure. */
+export interface ReadConfigOptions {
+    /** True for the explicit Run Config: a missing file is then an error. */
+    readonly required: boolean;
+}
+/**
+ * Reads, parses, and validates one config layer.
+ *
+ * A missing file at a discovered location yields `undefined` (an empty layer);
+ * a missing explicit Run Config fails. Any other errno — `EACCES`, say — always
+ * throws: a config yaag cannot read is not an empty config.
+ */
+export declare function readConfigLayer(path: string, options: ReadConfigOptions): Promise<ConfigLayer | undefined>;

package/assets/types/runtime/config/config-issues.d.ts

@@ -0,0 +1,12 @@
+import type { TLocalizedValidationError } from "typebox/error";
+/**
+ * Turns TypeBox errors into config diagnostics that name the offending key
+ * (spec rule 2).
+ *
+ * A strict object reports an unknown key twice: once at the key itself with the
+ * unhelpful `"schema is false"`, and once at the owning object carrying the key
+ * name. Neither alone reads well, so the pair collapses into one line. Every
+ * other keyword delegates to the shared formatter, which stays untouched
+ * because args validation and ADR-0032 steering text depend on its wording.
+ */
+export declare function describeConfigIssues(value: unknown, errors: Iterable<TLocalizedValidationError>): readonly string[];

package/assets/types/runtime/config/config-paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The part of the environment this module reads. It is structural on purpose:
+ * the vendored declaration tree compiles with no ambient Node globals.
+ */
+export interface ConfigEnvironment {
+    readonly [name: string]: string | undefined;
+}
+/** Every config layer lives in a file with this name. */
+export declare const CONFIG_FILE_NAME = "config.json";
+/** The Project Config directory inside a Program Directory. */
+export declare const PROJECT_CONFIG_DIR = ".yaag";
+/**
+ * Resolves the Global Config path: `YAAG_CONFIG_DIR`, then an absolute
+ * `XDG_CONFIG_HOME`, then `$HOME/.config`. A relative `XDG_CONFIG_HOME` is
+ * ignored (XDG spec), exactly as in `resolveCheckpointDirectory`.
+ */
+export declare function resolveGlobalConfigPath(env?: ConfigEnvironment): string;
+/**
+ * Resolves the Project Config path under a Program Directory. The Program
+ * Directory is an input: this module never walks upward looking for `.yaag/`.
+ */
+export declare function projectConfigPath(programDirectory: string): string;

package/assets/types/runtime/config/config-schema.d.ts

@@ -0,0 +1,17 @@
+import { type Static, Type } from "typebox";
+/**
+ * The config document of one layer (spec rule 1): plain JSON, namespaced as
+ * `{ "agents": { "extensions": ["..."] } }`.
+ *
+ * Every node sets `additionalProperties: false` on purpose (spec rule 2) — the
+ * opposite choice from `cassette-schema.ts`, which tolerates unknown fields so
+ * a newer artifact still loads. A config file is hand-written, so an unknown
+ * key is a typo the author wants named, not forward compatibility.
+ */
+export declare const YaagConfigSchema: Type.TObject<{
+    agents: Type.TOptional<Type.TObject<{
+        extensions: Type.TOptional<Type.TArray<Type.TString>>;
+    }>>;
+}>;
+/** The validated shape of one config file. */
+export type YaagConfigDocument = Static<typeof YaagConfigSchema>;

package/assets/types/runtime/config/effective-config.d.ts

@@ -0,0 +1,42 @@
+import { type ConfigEnvironment } from "./config-paths.ts";
+/** Which of the three layers a config value came from. */
+export type ConfigLayerName = "global" | "project" | "run";
+/** One extension declaration, kept exactly as written, with its resolution base. */
+export interface ConfigExtension {
+    /** The declaration as written in the config file; never resolved here. */
+    readonly declaration: string;
+    /** The declaring config file's own directory (spec rule 4). */
+    readonly baseDirectory: string;
+    readonly layer: ConfigLayerName;
+    /** The declaring file, for diagnostics. */
+    readonly file: string;
+}
+/** The merged configuration one Run reads at start. */
+export interface EffectiveConfig {
+    /** Extension declarations, concatenated global → project → run (spec rule 3). */
+    readonly extensions: readonly ConfigExtension[];
+    /** Config files that contributed, in merge order. */
+    readonly files: readonly string[];
+}
+/** What to discover and read. */
+export interface EffectiveConfigRequest {
+    /** Environment for Global Config discovery; defaults to `process.env`. */
+    readonly env?: ConfigEnvironment;
+    /** Program Directory of the Run; absent means no Project Config layer. */
+    readonly programDirectory?: string;
+    /** Explicit Run Config path; a missing file here is an error. */
+    readonly configPath?: string;
+    /** Suppresses the discovered layers only; an explicit `configPath` survives (spec rule 8). */
+    readonly noConfig?: boolean;
+}
+/** The Effective Config of a Run that found no config at all. */
+export declare const EMPTY_EFFECTIVE_CONFIG: EffectiveConfig;
+/**
+ * Locates, reads, validates, and merges the three config layers.
+ *
+ * The result is frozen: the Effective Config is read once at Run start, so a
+ * config edit mid-Run changes nothing until the next Run (spec rule 6). Nothing
+ * is resolved, existence-checked, or deduplicated here — dedup happens by
+ * resolved path once the spawn knows its base directories (ADR-0040).
+ */
+export declare function loadEffectiveConfig(request?: EffectiveConfigRequest): Promise<EffectiveConfig>;

package/assets/types/runtime/config/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public surface of the `config/` module: the Global, Project, and Run Config
+ * layers and the frozen Effective Config a Run reads at start (ADR-0040).
+ * Files inside this directory import each other directly.
+ */
+export { CONFIG_FILE_NAME, type ConfigEnvironment, PROJECT_CONFIG_DIR, projectConfigPath, resolveGlobalConfigPath, } from "./config-paths.ts";
+export type { YaagConfigDocument } from "./config-schema.ts";
+export { type ConfigExtension, type ConfigLayerName, type EffectiveConfig, type EffectiveConfigRequest, EMPTY_EFFECTIVE_CONFIG, loadEffectiveConfig, } from "./effective-config.ts";

package/assets/types/runtime/errors.d.ts

@@ -30,7 +30,7 @@ export interface ModelResolutionOutcome {
     readonly modelErrors: readonly ModelError[];
 }
 /** Why an Ask, spawn, or Run failed. Programs may branch on this; most won't. */
-export type YaagErrorCode = "AGENT_FAILED" | "AGENT_DIED" | "AGENT_BUSY" | "ASK_TIMEOUT" | "ASK_LIMIT" | "ASK_STALLED" | "ASK_INVALID_OUTPUT" | "ARGS_INVALID" | "OPTIONS_CONFLICT" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "MODEL_RESOLUTION_FAILED" | "SPAWN_FAILED";
+export type YaagErrorCode = "AGENT_FAILED" | "AGENT_DIED" | "AGENT_BUSY" | "ASK_TIMEOUT" | "ASK_LIMIT" | "ASK_STALLED" | "ASK_INVALID_OUTPUT" | "ARGS_INVALID" | "CONFIG_INVALID" | "OPTIONS_CONFLICT" | "REPLAY_DIVERGED" | "RESUME_REFUSED" | "RUN_CLOSED" | "RUN_STOPPED" | "WORKTREE_REFUSED" | "MODEL_RESOLUTION_FAILED" | "SPAWN_FAILED";
 /** The single error class of the runtime (ADR-0003). */
 export declare class YaagError extends Error {
     readonly code: YaagErrorCode;

package/assets/types/runtime/extension/extension-paths.d.ts

@@ -3,14 +3,22 @@ import { type ExtensionInstallRoots } from "./extension-package.ts";
 export interface ExtensionResolutionOptions extends ExtensionInstallRoots {
     /** Orchestration Program source path, required by relative declarations. */
     readonly programFile?: string;
+    /**
+     * Directory a relative declaration resolves against, and which wins over
+     * `programFile`: a config-sourced entry resolves from its own config file's
+     * directory (ADR-0040, spec rule 4).
+     */
+    readonly baseDirectory?: string;
 }
 /**
  * Resolves declared extensions into launch-ready `pi -e` arguments before transport opening.
  *
- * Filesystem declarations are resolved against the Orchestration Program directory and
+ * Filesystem declarations are resolved against `baseDirectory` when given, and against
+ * the Orchestration Program directory otherwise, and are
  * checked for existence. `npm:`/`git:` specifiers expand to the entry points of the
  * already-installed package (project install shadows the user install); an uninstalled
  * specifier passes through verbatim so pi temp-installs it. Results retain declaration
- * order. Rejects missing paths and a relative declaration without `programFile`.
+ * order. Rejects missing paths, and a relative declaration that has neither
+ * `baseDirectory` nor `programFile`.
  */
 export declare function resolveExtensionPaths(declarations: readonly string[], options?: ExtensionResolutionOptions): Promise<readonly string[]>;

package/assets/types/runtime/index.d.ts

@@ -2,6 +2,8 @@ export type { AgentConfig, AgentDefinition } from "./agent/index.ts";
 export { agentDefinitionConfig, defineAgent, isAgentDefinition } from "./agent/index.ts";
 export type { Cassette, CassetteAgent, CassetteArtifact, CassetteAsk, CassetteGit, CassetteRun, CassetteSink, CassetteSpawn, } from "./cassette/index.ts";
 export { assertReplayable, CASSETTE_VERSION, loadCassette, recordingTransport, replayTransport, resumeTransport, } from "./cassette/index.ts";
+export type { ConfigEnvironment, ConfigExtension, ConfigLayerName, EffectiveConfig, EffectiveConfigRequest, } from "./config/index.ts";
+export { EMPTY_EFFECTIVE_CONFIG, loadEffectiveConfig, PROJECT_CONFIG_DIR, } from "./config/index.ts";
 export type { AskInvalidOutputOutcome, AskLimitKind, AskLimitOutcome, AskStalledOutcome, ModelResolutionOutcome, YaagErrorCode, } from "./errors.ts";
 export { isYaagError, YaagError } from "./errors.ts";
 export type { AgentActivity, AskOutputChannel, EventSink, LifecycleEvent, LifecycleEventBody, NodeState, NodeUsage, StampedEventSink, } from "./events.ts";

package/assets/types/runtime/run/run.d.ts

@@ -1,4 +1,5 @@
 import { type Cassette, type CassetteSink } from "../cassette/index.ts";
+import { type EffectiveConfig } from "../config/index.ts";
 import type { StampedEventSink } from "../events.ts";
 import type { TransportFactory } from "../transport/index.ts";
 import { type SkillProbeFactory } from "../transport/index.ts";
@@ -33,6 +34,12 @@ export interface RunOptions {
     readonly signal?: AbortSignal;
     /** Overrides the default checkpoint directory a stopped Run publishes into (ADR-0021). */
     readonly checkpointDir?: string;
+    /**
+     * Effective Config for this Run, read once by the launcher (ADR-0040). The
+     * Run never loads it itself: omission runs config-free, so no Run picks up a
+     * config it was not given, and every test stays hermetic.
+     */
+    readonly config?: EffectiveConfig;
 }
 /**
  * Executes one Orchestration Program and resolves with its return value.

package/assets/types/runtime/transport/transport.d.ts

@@ -157,6 +157,11 @@ export interface OpenOptions {
     readonly resolvedSkillPaths?: readonly string[];
     /** Absolute launch-ready extension paths resolved above the seam, emitted as repeated `-e` flags. */
     readonly resolvedExtensionPaths?: readonly string[];
+    /**
+     * Declared extensions in final concatenation order, unresolved (ADR-0040).
+     * Spawn identity only: it never becomes argv, and it is absent when empty.
+     */
+    readonly declaredExtensions?: readonly string[];
     /** Session storage directory. Used by the e2e suite to stay out of ~/.pi (ticket 06). */
     readonly sessionDir?: string;
     /** Resumes an existing pi session, translated to `--session <path>`. */

package/assets/types/runtime/types.d.ts

@@ -36,6 +36,11 @@ export interface SpawnOptions {
      * resolve from the Orchestration Program file; each becomes `pi -e <path>`.
      */
     readonly extensions?: readonly string[];
+    /**
+     * Load the Effective Config's `agents.extensions` for this Agent. Default
+     * true; false spawns with only the extensions this call declares (ADR-0040).
+     */
+    readonly configExtensions?: boolean;
     /**
      * Tool allowlist layered over the ADR-0026 baseline; omission is tool-free when hermetic.
      * `disallowedTools` applies last. A non-empty surviving allowlist is verified after startup;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -21,8 +21,8 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.7.0",
-    "@yaag/tui": "0.7.0",
+    "@yaag/runtime": "0.8.0",
+    "@yaag/tui": "0.8.0",
     "typebox": "1.3.7"
   }
 }

package/src/argv.ts

@@ -5,9 +5,9 @@
 import { resolve } from "node:path";
 
 export const USAGE = `usage:
-  yaag run <program.ts> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
-  yaag run --eval <source> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
-  yaag run --eval-fd <n> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>]
+  yaag run <program.ts> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
+  yaag run --eval <source> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
+  yaag run --eval-fd <n> [--quiet] [--args <json>] [--record <file>] [--replay <file>] [--resume <file>] [--events-fd <n>] [--config <file>] [--no-config]
   yaag describe <program.ts>
   yaag setup-workspace [dir]
 
@@ -20,6 +20,12 @@ must be a file.
 close that descriptor. It keeps the source out of the process argument list,
 where every local user can read it. The yaag extension always uses it.
 
+--config <file> reads one more config file for this Run. Give it one time only.
+yaag reads it after the global config and after the project config.
+
+--no-config tells yaag to ignore the global config and the project config. It
+does not ignore --config.
+
 A --resume or --replay Run also needs the program: give the program file,
 --eval <source>, or --eval-fd <n>. A Cassette holds the history of a Run, and never the program
 to run.
@@ -44,6 +50,8 @@ export type ParsedArgv =
       readonly record?: string;
       readonly replay?: string;
       readonly resume?: string;
+      readonly config?: string;
+      readonly noConfig?: boolean;
     }
   | { readonly ok: true; readonly command: "describe"; readonly file: string }
   | { readonly ok: true; readonly command: "setup-workspace"; readonly dir: string }
@@ -72,12 +80,16 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
   let record: string | undefined;
   let replay: string | undefined;
   let resume: string | undefined;
+  let config: string | undefined;
+  let noConfig = false;
   let quiet = false;
 
   for (let index = 0; index < tokens.length; index += 1) {
     const token = tokens[index] ?? "";
     if (token === "--quiet") {
       quiet = true;
+    } else if (token === "--no-config") {
+      noConfig = true;
     } else if (
       token === "--args" ||
       token === "--eval" ||
@@ -85,7 +97,8 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
       token === "--events-fd" ||
       token === "--record" ||
       token === "--replay" ||
-      token === "--resume"
+      token === "--resume" ||
+      token === "--config"
     ) {
       const value = tokens[index + 1];
       if (value === undefined) return failure(`${token} needs a value\n${USAGE}`);
@@ -108,6 +121,10 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
         record = value;
       } else if (token === "--replay") {
         replay = value;
+      } else if (token === "--config") {
+        // One Run Config only: two of them would leave the merge order unstated.
+        if (config !== undefined) return failure(`--config may be given once\n${USAGE}`);
+        config = value;
       } else {
         resume = value;
       }
@@ -134,6 +151,8 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
     ...(record === undefined ? {} : { record }),
     ...(replay === undefined ? {} : { replay }),
     ...(resume === undefined ? {} : { resume }),
+    ...(config === undefined ? {} : { config }),
+    ...(noConfig ? { noConfig: true } : {}),
   };
 }
 

package/src/cli.ts

@@ -10,6 +10,7 @@ import {
   type StampedEventSink,
 } from "@yaag/runtime";
 import { parseArgv } from "./argv.ts";
+import { loadRunConfig } from "./config/index.ts";
 import { loadProgram, loadRunProgram, registerRuntimeAlias } from "./program/index.ts";
 import { setupWorkspace } from "./setup-workspace.ts";
 import {
@@ -47,6 +48,13 @@ export async function main(argv: readonly string[]): Promise<number> {
       await loadCassette(parsed.resume);
     }
     if (parsed.command === "describe") return describe(await loadProgram(resolve(parsed.file)));
+    // Before the program import: a bad config must fail the Run at start, and
+    // never after an arbitrary program module ran its top level (ADR-0040).
+    const config = await loadRunConfig({
+      programFile: parsed.program.kind === "file" ? resolve(parsed.program.file) : undefined,
+      ...(parsed.config === undefined ? {} : { configPath: parsed.config }),
+      ...(parsed.noConfig === true ? { noConfig: true } : {}),
+    });
     const { program, programFile, programSource } = await loadRunProgram(parsed.program);
     return await run(program, {
       programFile,
@@ -56,6 +64,7 @@ export async function main(argv: readonly string[]): Promise<number> {
       record: parsed.record,
       replay: parsed.replay,
       resume: parsed.resume,
+      config,
       quiet: parsed.quiet,
     });
   } catch (error) {

package/src/config/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public surface of the CLI's `config/` module: Program Directory discovery and
+ * the launcher's Effective Config read (ADR-0040).
+ * Files inside this directory import each other directly.
+ */
+
+export { findProgramDirectory } from "./program-directory.ts";
+export { loadRunConfig, type RunConfigRequest } from "./run-config.ts";

package/src/config/program-directory.ts

@@ -0,0 +1,34 @@
+/**
+ * Program Directory discovery for the launcher.
+ *
+ * The runtime's `config-paths.ts` never walks upward: it takes the Program
+ * Directory as an input. The CLI is the launcher, so the walk lives here
+ * (ADR-0040).
+ */
+import { stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { PROJECT_CONFIG_DIR } from "@yaag/runtime";
+
+/**
+ * The nearest directory at or above `startDirectory` that holds a `.yaag`
+ * directory, or `undefined` when the walk reaches the filesystem root.
+ *
+ * A `.yaag` file is not a marker: only a directory can hold a config file.
+ */
+export async function findProgramDirectory(startDirectory: string): Promise<string | undefined> {
+  let directory = resolve(startDirectory);
+  for (;;) {
+    if (await hasMarker(directory)) return directory;
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+async function hasMarker(directory: string): Promise<boolean> {
+  try {
+    return (await stat(join(directory, PROJECT_CONFIG_DIR))).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/config/run-config.ts

@@ -0,0 +1,54 @@
+/**
+ * The launcher's config read: it resolves the Program Directory of one Run and
+ * loads the Effective Config from the three layers (ADR-0040).
+ *
+ * `RunOptions.config` is read once, here, at Run start. Nothing else in the
+ * process reads a config file.
+ */
+import { dirname, resolve } from "node:path";
+import { type ConfigEnvironment, type EffectiveConfig, loadEffectiveConfig } from "@yaag/runtime";
+import { findProgramDirectory } from "./program-directory.ts";
+
+/** What one Run needs to know to find its config layers. */
+export interface RunConfigRequest {
+  /** Absolute path of the program file; `undefined` for an Inline Program. */
+  readonly programFile: string | undefined;
+  /** Where an Inline Program starts its search; defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** The `--config` value, absolute or relative to `cwd`. */
+  readonly configPath?: string;
+  /** `--no-config`: drops the Global and the Project layer only (spec rule 8). */
+  readonly noConfig?: boolean;
+  /** Environment for Global Config discovery; defaults to `process.env`. */
+  readonly env?: ConfigEnvironment;
+}
+
+/**
+ * Loads the Effective Config of one Run.
+ *
+ * The Program Directory search starts at the program file's directory, or at
+ * `cwd` for an Inline Program. `--no-config` skips the search: no discovered
+ * layer can contribute, so nothing must be looked for.
+ *
+ * Throws `YaagError("CONFIG_INVALID", …)` when a config file is missing at the
+ * explicit `--config` path, or when any layer is unreadable or invalid.
+ */
+export async function loadRunConfig(request: RunConfigRequest): Promise<EffectiveConfig> {
+  const cwd = request.cwd ?? process.cwd();
+  const configPath =
+    request.configPath === undefined ? undefined : resolve(cwd, request.configPath);
+  // `--no-config` discovers nothing, so the upward walk is skipped: it would
+  // stat directory after directory for a layer that cannot contribute.
+  const programDirectory =
+    request.noConfig === true
+      ? undefined
+      : await findProgramDirectory(
+          request.programFile === undefined ? cwd : dirname(request.programFile),
+        );
+  return await loadEffectiveConfig({
+    ...(request.env === undefined ? {} : { env: request.env }),
+    ...(request.noConfig === true ? { noConfig: true } : {}),
+    ...(programDirectory === undefined ? {} : { programDirectory }),
+    ...(configPath === undefined ? {} : { configPath }),
+  });
+}

package/src/terminal/run-invocation.ts

@@ -5,7 +5,7 @@
  * Both presentation paths — the plain lines and the alt-screen tree — compose
  * it, so they cannot drift on artifact flags or on the result format.
  */
-import type { RunOptions, StampedEventSink } from "@yaag/runtime";
+import type { EffectiveConfig, RunOptions, StampedEventSink } from "@yaag/runtime";
 
 /** Everything `yaag run` parsed for one Run. */
 export interface RunFlags {
@@ -18,6 +18,8 @@ export interface RunFlags {
   readonly record: string | undefined;
   readonly replay: string | undefined;
   readonly resume: string | undefined;
+  /** The Effective Config the launcher read at Run start (ADR-0040). */
+  readonly config: EffectiveConfig | undefined;
   readonly quiet: boolean;
 }
 
@@ -35,6 +37,7 @@ export function executeOptions(
     ...(flags.record === undefined ? {} : { record: flags.record }),
     ...(flags.replay === undefined ? {} : { replay: flags.replay }),
     ...(flags.resume === undefined ? {} : { resume: flags.resume }),
+    ...(flags.config === undefined ? {} : { config: flags.config }),
     signal,
   };
 }