@yaag/cli 0.2.0 → 0.3.0

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

@@ -13,6 +13,7 @@ export declare const CassetteSchema: Type.TObject<{
     run: Type.TOptional<Type.TObject<{
         outcome: Type.TUnion<Type.TLiteral<"completed" | "failed" | "interrupted" | "paused" | "stopped">[]>;
         programFile: Type.TOptional<Type.TString>;
+        programSource: Type.TOptional<Type.TString>;
         args: Type.TOptional<Type.TUnknown>;
         programHash: Type.TOptional<Type.TString>;
     }>>;

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

@@ -11,8 +11,10 @@ export interface CassetteRun {
     readonly outcome: RunOutcome;
     /** Invocation identity: what a resume is about to re-execute. */
     readonly programFile?: string;
+    /** Inline Program source text; identity for a Run with no program file (ADR-0033). */
+    readonly programSource?: string;
     readonly args?: unknown;
-    /** Advisory content hash of the program file; SHA-256 hex. */
+    /** Advisory content hash of the program file, or of the inline source; SHA-256 hex. */
     readonly programHash?: string;
 }
 /** Versioned JSON artifact containing the frames exchanged during one Run. */

package/assets/types/runtime/program-hash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * One advisory content hash, shared by the modules that record a program's
+ * identity and the modules that compare it (ADR-0033).
+ */
+/** Advisory content hash of a program's bytes or inline source; SHA-256 hex. */
+export declare function sha256Hex(input: string | ArrayBuffer): string;

package/assets/types/runtime/resume-identity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The advisory comparison between a loaded Cassette's recorded program identity
+ * and the program this Run executes (ADR-0033).
+ */
+import type { Cassette } from "./cassette.ts";
+import type { ProgramIdentity } from "./run-checkpoint.ts";
+/**
+ * Warns when a Cassette's recorded program identity does not match the program
+ * this Run executes. Advisory only: the caller always supplies the program and
+ * the Cassette supplies the history, so a mismatch never stops the Run
+ * (ADR-0033). Returns null when nothing inline is involved, so file-to-file
+ * resume behaviour is unchanged.
+ */
+export declare function programIdentityWarning(cassette: Cassette, path: string, program: ProgramIdentity): string | null;

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

@@ -44,7 +44,13 @@ export declare function publishRunCheckpoint(options: RunCheckpointOptions): Pro
  * today's rule that its directory must already exist.
  */
 export declare function ensureCheckpointDirectory(record: string | undefined, destination: string): Promise<void>;
+/** Which program a Run executes: a file on disk, or inline source text (ADR-0033). */
+export interface ProgramIdentity {
+    readonly programFile?: string;
+    /** Inline source, exactly as the caller gave it; it excludes any loader prelude. */
+    readonly programSource?: string;
+}
 /** Resolves what a resume re-executes. The program hash is advisory only. */
-export declare function resolveRunIdentity(programFile: string | undefined, args: unknown): Promise<RunIdentity>;
+export declare function resolveRunIdentity(program: ProgramIdentity, args: unknown): Promise<RunIdentity>;
 /** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
 export declare function writeRecordingDiagnostic(error: unknown): void;

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

@@ -16,6 +16,11 @@ export interface RunOptions {
      * extension declarations. This is Run context, never an Agent working directory.
      */
     readonly programFile?: string;
+    /**
+     * Inline Program source text, recorded as the Run's identity when there is no
+     * program file (ADR-0033). It never resolves extension paths.
+     */
+    readonly programSource?: string;
     /** Resolves pi's enabled skills for live restriction requests. */
     readonly skillProbe?: SkillProbeFactory;
     /** Write every public transport-seam frame once the Run settles. */

package/package.json

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

package/src/argv.ts

@@ -6,16 +6,31 @@ 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 describe <program.ts>
   yaag setup-workspace [dir]
 
+--eval runs an Orchestration Program that you give as source text. Give a
+program file or --eval, but do not give both. A program that --eval runs can
+import "@yaag/runtime" and "typebox" only. A program that imports other modules
+must be a file.
+
+A --resume or --replay Run also needs the program: give the program file, or
+--eval <source>. A Cassette holds the history of a Run, and never the program
+to run.
+
 Warning: describe imports the module and executes its top level. Keep program module top level side-effect free.`;
 
+/** The program one `run` invocation names: a file, or source text (ADR-0033). */
+export type ProgramSource =
+  | { readonly kind: "file"; readonly file: string }
+  | { readonly kind: "inline"; readonly source: string };
+
 export type ParsedArgv =
   | {
       readonly ok: true;
       readonly command: "run";
-      readonly file: string;
+      readonly program: ProgramSource;
       /** Opaque: parsed JSON, never validated here (ADR-0010). */
       readonly args: unknown;
       readonly quiet: boolean;
@@ -44,6 +59,7 @@ export function parseArgv(argv: readonly string[]): ParsedArgv {
 
 function parseRun(tokens: readonly string[]): ParsedArgv {
   let file: string | undefined;
+  let evalSource: string | undefined;
   let args: unknown = {};
   let eventsFd: number | undefined;
   let record: string | undefined;
@@ -57,6 +73,7 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
       quiet = true;
     } else if (
       token === "--args" ||
+      token === "--eval" ||
       token === "--events-fd" ||
       token === "--record" ||
       token === "--replay" ||
@@ -69,6 +86,8 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
         const parsed = parseJson(value);
         if (!parsed.ok) return parsed;
         args = parsed.value;
+      } else if (token === "--eval") {
+        evalSource = value;
       } else if (token === "--events-fd") {
         const parsed = parseDescriptor(value);
         if (!parsed.ok) return parsed;
@@ -89,20 +108,14 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
     }
   }
 
-  if (file === undefined) return failure(USAGE);
-  if (record !== undefined && replay !== undefined) {
-    return failure(`--record and --replay cannot be used together\n${USAGE}`);
-  }
-  if (resume !== undefined && replay !== undefined) {
-    return failure(`--resume and --replay cannot be used together\n${USAGE}`);
-  }
-  if (resume !== undefined && record !== undefined && resolve(resume) === resolve(record)) {
-    return failure(`--resume and --record must use different paths\n${USAGE}`);
-  }
+  const clash = conflict({ file, evalSource, record, replay, resume });
+  if (clash !== null) return failure(`${clash}\n${USAGE}`);
+  const program = programSource(file, evalSource);
+  if (program === undefined) return missingProgram(resume, replay);
   return {
     ok: true,
     command: "run",
-    file,
+    program,
     args,
     quiet,
     ...(eventsFd === undefined ? {} : { eventsFd }),
@@ -112,6 +125,53 @@ function parseRun(tokens: readonly string[]): ParsedArgv {
   };
 }
 
+interface RunFlags {
+  readonly file?: string;
+  readonly evalSource?: string;
+  readonly record?: string;
+  readonly replay?: string;
+  readonly resume?: string;
+}
+
+/** Names the first pair of options that cannot appear in one invocation. */
+function conflict(flags: RunFlags): string | null {
+  const { file, evalSource, record, replay, resume } = flags;
+  if (file !== undefined && evalSource !== undefined) {
+    return "--eval and a program file cannot be used together";
+  }
+  if (record !== undefined && replay !== undefined) {
+    return "--record and --replay cannot be used together";
+  }
+  if (resume !== undefined && replay !== undefined) {
+    return "--resume and --replay cannot be used together";
+  }
+  if (resume !== undefined && record !== undefined && resolve(resume) === resolve(record)) {
+    return "--resume and --record must use different paths";
+  }
+  return null;
+}
+
+/** A Cassette is history, never an execution source, so the caller gives the program (ADR-0033). */
+function missingProgram(
+  resume: string | undefined,
+  replay: string | undefined,
+): { readonly ok: false; readonly error: string } {
+  if (resume === undefined && replay === undefined) return failure(USAGE);
+  const flag = resume !== undefined ? "--resume" : "--replay";
+  return failure(
+    `${flag} needs the program too: give <program.ts> or --eval <source>. ` +
+      `A cassette holds the history of a Run, and never the program to run.\n${USAGE}`,
+  );
+}
+
+function programSource(
+  file: string | undefined,
+  source: string | undefined,
+): ProgramSource | undefined {
+  if (source !== undefined) return { kind: "inline", source };
+  return file === undefined ? undefined : { kind: "file", file };
+}
+
 function parseDescribe(tokens: readonly string[]): ParsedArgv {
   if (tokens.length !== 1 || tokens[0]?.startsWith("-")) return failure(USAGE);
   return { ok: true, command: "describe", file: tokens[0] };

package/src/cli-tree-host.ts

@@ -1,9 +1,9 @@
 /**
- * The read-only half of `RunTreeViewHost` for the standalone CLI (spec §4).
+ * The read-only half of `RunTreeViewHost` for the standalone CLI (ADR-0008).
  *
  * The Host Session gets the same shape from `packages/extension`; here the pi
  * services are replaced by pi-tui primitives, so `apps/yaag` needs no pi. The
- * caller adds `stop`, `detach`, and `done`: nothing in this module can prompt
+ * caller adds `stop` and `done`: nothing in this module can prompt
  * an Agent (ADR — a Peek observes, it never sends).
  */
 import { readFile, writeFile } from "node:fs/promises";
@@ -26,7 +26,7 @@ export interface CliTreeHostOptions {
 }
 
 /** The read-only capabilities the CLI Run view has. */
-export type ReadOnlyCliHost = Omit<RunTreeViewHost, "stop" | "detach" | "done">;
+export type ReadOnlyCliHost = Omit<RunTreeViewHost, "stop" | "done">;
 
 /** Builds the CLI's read-only host; it never writes to an Agent or to the Run. */
 export function createCliTreeHost(options: CliTreeHostOptions): ReadOnlyCliHost {

package/src/cli.ts

@@ -3,7 +3,6 @@ import { resolve } from "node:path";
 import {
   assertReplayable,
   executeRun,
-  isOrchestrationProgram,
   isYaagError,
   loadCassette,
   type OrchestrationProgram,
@@ -15,7 +14,9 @@ import { parseArgv } from "./argv.ts";
 import { runInteractive } from "./interactive-run.ts";
 import { writeChannel, writeChannelFd } from "./output-channel.ts";
 import { createPlainPresenter } from "./presenter.ts";
+import { loadProgram } from "./program-loader.ts";
 import { executeOptions, formatResult, type RunFlags } from "./run-invocation.ts";
+import { loadRunProgram } from "./run-program.ts";
 import { registerRuntimeAlias } from "./runtime-alias.ts";
 import { setupWorkspace } from "./setup-workspace.ts";
 
@@ -42,11 +43,11 @@ export async function main(argv: readonly string[]): Promise<number> {
     if (parsed.command === "run" && parsed.resume !== undefined) {
       await loadCassette(parsed.resume);
     }
-    const programFile = resolve(parsed.file);
-    const program = await loadProgram(programFile);
-    if (parsed.command === "describe") return describe(program);
+    if (parsed.command === "describe") return describe(await loadProgram(resolve(parsed.file)));
+    const { program, programFile, programSource } = await loadRunProgram(parsed.program);
     return await run(program, {
       programFile,
+      programSource,
       args: parsed.args,
       eventsFd: parsed.eventsFd,
       record: parsed.record,
@@ -142,19 +143,6 @@ function eventSink(fd: number | undefined, present: StampedEventSink): StampedEv
   };
 }
 
-/** The program is the module's default export, and nothing else will do. */
-async function loadProgram(path: string): Promise<OrchestrationProgram> {
-  const module: unknown = await import(path);
-  const program =
-    typeof module === "object" && module !== null && "default" in module
-      ? module.default
-      : undefined;
-  if (!isOrchestrationProgram(program)) {
-    throw new Error(`${path}: export defineRun({ run }) as the default export`);
-  }
-  return program;
-}
-
 if (import.meta.main) {
   const code = await main(process.argv.slice(2));
   // Exit rather than wait for the loop to drain: a stopped Run may leave the

package/src/computed-imports.ts

@@ -0,0 +1,101 @@
+/**
+ * Finds a dynamic `import(...)` whose specifier is not one plain string
+ * literal.
+ *
+ * The specifier of such a call only exists while the program runs, so a scan
+ * of the literal specifiers cannot see it, and Bun resolves a built-in module
+ * and an absolute path without asking a resolver plugin. The call is refused
+ * as syntax, before the source becomes a module (ADR-0033). The `require`
+ * binding needs no scan here: `inline-program.ts` replaces it when the module
+ * loads, so every `require` call is checked when it runs.
+ *
+ * The scan reads the raw text and does not tokenize. `import` is a reserved
+ * word: real code cannot write it with escape sequences, cannot split it, and
+ * cannot put an identifier character or a `.` directly before a dynamic
+ * import. So each dynamic import in real code is an occurrence of the word
+ * `import` in the raw text, and a check of every occurrence misses none — no
+ * reading of a comment, string, or regular expression can hide one. The cost
+ * is the reverse case: text that only looks like a computed dynamic import,
+ * for example in a prompt string, is also refused. That refusal is safe, and
+ * the caller fixes it by making the program a file.
+ */
+
+/** One `import(...)` shape whose specifier is not one plain string literal. */
+export interface ComputedImport {
+  /** 1-based line of the `import` word in the scanned source. */
+  readonly line: number;
+}
+
+/** Returns the first computed dynamic `import(...)` shape, or `undefined`. */
+export function findComputedImport(source: string): ComputedImport | undefined {
+  for (let from = 0; ; ) {
+    const at = source.indexOf("import", from);
+    if (at === -1) return undefined;
+    from = at + "import".length;
+    if (isWordChar(source[at - 1]) || source[at - 1] === "." || isWordChar(source[from])) continue;
+    const open = skipTrivia(source, from);
+    if (source[open] !== "(") continue;
+    if (!takesOneStringLiteral(source, open + 1)) return { line: lineAt(source, at) };
+  }
+}
+
+/**
+ * True when the argument list that starts at `from` opens with one plain
+ * string literal, followed by `)` or by a `,` and more arguments.
+ *
+ * When the occurrence is real code, the trivia around the literal is real
+ * trivia, so this reads exactly what Bun reads. When the occurrence is inert
+ * text, a wrong reading can only refuse a harmless program.
+ */
+function takesOneStringLiteral(source: string, from: number): boolean {
+  const start = skipTrivia(source, from);
+  const quote = source[start];
+  if (quote !== '"' && quote !== "'") return false;
+  const end = endOfQuoted(source, start);
+  if (end === undefined) return false;
+  const next = source[skipTrivia(source, end)];
+  return next === ")" || next === ",";
+}
+
+/** True for a character that can continue an identifier. */
+function isWordChar(char: string | undefined): boolean {
+  return char !== undefined && /[\w$]/.test(char);
+}
+
+/** The index after the whitespace and comments that start at `index`. */
+function skipTrivia(source: string, index: number): number {
+  let cursor = index;
+  for (;;) {
+    while (/\s/.test(source[cursor] ?? "")) cursor += 1;
+    if (source[cursor] === "/" && source[cursor + 1] === "/") {
+      const line = source.indexOf("\n", cursor);
+      cursor = line === -1 ? source.length : line + 1;
+    } else if (source[cursor] === "/" && source[cursor + 1] === "*") {
+      const end = source.indexOf("*/", cursor + 2);
+      cursor = end === -1 ? source.length : end + 2;
+    } else {
+      return cursor;
+    }
+  }
+}
+
+/** The index after a `'` or `"` string, or `undefined` when the line ends first. */
+function endOfQuoted(source: string, start: number): number | undefined {
+  const quote = source[start];
+  for (let index = start + 1; index < source.length; index += 1) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 1;
+      continue;
+    }
+    if (char === "\n") return undefined;
+    if (char === quote) return index + 1;
+  }
+  return undefined;
+}
+
+function lineAt(source: string, index: number): number {
+  let line = 1;
+  for (let cursor = 0; cursor < index; cursor += 1) if (source[cursor] === "\n") line += 1;
+  return line;
+}

package/src/inline-imports.ts

@@ -0,0 +1,76 @@
+/**
+ * The closed import contract of an Inline Program (ADR-0033).
+ *
+ * An Inline Program can import `@yaag/runtime` and `typebox` only. Placement
+ * in `os.tmpdir()` stops relative and project-package resolution, but it stops
+ * neither a built-in module such as `node:fs` nor an absolute path, and
+ * removal of the module file stops neither one either. Three checks close the
+ * contract. Before the source becomes a module: each literal specifier that
+ * Bun's parser reports must be allowed, and a dynamic `import(...)` whose
+ * specifier is not one plain string literal is refused as syntax. While the
+ * module runs: `inlineRequirePrelude` replaces the `require` binding and
+ * `import.meta.require`, so every `require` call — direct, aliased, or
+ * computed — is checked with its real specifier when it runs.
+ */
+import { findComputedImport } from "./computed-imports.ts";
+
+/** The only specifiers an Inline Program can import. */
+export const ALLOWED_INLINE_IMPORTS: readonly string[] = ["@yaag/runtime", "typebox"];
+
+/**
+ * Rejects an Inline Program that imports outside the closed contract.
+ *
+ * Refuses a dynamic `import(...)` whose specifier is not one plain string
+ * literal, then reads each literal specifier — static import, export-from,
+ * `require` call, and dynamic `import()` — and refuses one that is not
+ * allowed. Throws `Error` on the first refusal, and on source text that does
+ * not parse. The refusal happens before the source becomes a module, so no
+ * disallowed module is loaded. A `require` call that computes its specifier
+ * passes this check; `inlineRequirePrelude` refuses it when it runs, before
+ * any module resolves.
+ */
+export function assertClosedImports(source: string): void {
+  const computed = findComputedImport(source);
+  if (computed !== undefined) {
+    throw new Error(
+      `inline program cannot import a computed specifier ` +
+        `(import call on line ${computed.line}): ` +
+        `--eval allows ${allowedText()} only, each one as a string literal`,
+    );
+  }
+  const transpiler = new Bun.Transpiler({ loader: "ts" });
+  for (const scanned of transpiler.scanImports(source)) {
+    if (ALLOWED_INLINE_IMPORTS.includes(scanned.path)) continue;
+    throw new Error(
+      `inline program cannot import ${JSON.stringify(scanned.path)}: ` +
+        `--eval allows ${allowedText()} only`,
+    );
+  }
+}
+
+/**
+ * One line of code that `inline-program.ts` puts before an Inline Program.
+ *
+ * The line shadows the module-scope `require` binding with a wrapper that
+ * refuses every specifier outside `ALLOWED_INLINE_IMPORTS`, and puts the same
+ * wrapper on `import.meta.require`. Every `require` call — direct, aliased,
+ * stored in a variable, written with identifier escape sequences, or reached
+ * through `import.meta` — runs the wrapper, so this check does not depend on
+ * a reading of the source. An allowed specifier goes to the real `require`
+ * unchanged. The line holds no line break, so it moves each source line down
+ * by exactly one.
+ */
+export function inlineRequirePrelude(): string {
+  const suffix = JSON.stringify(`: --eval allows ${allowedText()} only`);
+  return [
+    "const require = ((real, allowed) => (id) => {",
+    " if (allowed.includes(id)) return real(id);",
+    ` throw new Error("inline program cannot require " + JSON.stringify(id) + ${suffix});`,
+    ` })(import.meta.require, ${JSON.stringify(ALLOWED_INLINE_IMPORTS)});`,
+    " import.meta.require = require;",
+  ].join("");
+}
+
+function allowedText(): string {
+  return ALLOWED_INLINE_IMPORTS.map((name) => JSON.stringify(name)).join(" and ");
+}

package/src/inline-program.ts

@@ -0,0 +1,49 @@
+/**
+ * Loads an Inline Program: source text that a caller gives instead of a file.
+ *
+ * The source goes to a temporary `.ts` file in `os.tmpdir()`, through the same
+ * loader a file program uses, and the file is unlinked whether the import
+ * succeeds or throws. A real file gives real module resolution and real stack
+ * traces. The import contract is closed (ADR-0033): before the source becomes
+ * a module, `inline-imports.ts` rejects each literal specifier other than
+ * `@yaag/runtime` and `typebox` and each computed `import(...)`; while the
+ * module runs, a one-line prelude before the source checks every `require`
+ * call with its real specifier.
+ */
+import { randomUUID } from "node:crypto";
+import { unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { OrchestrationProgram } from "@yaag/runtime";
+import { assertClosedImports, inlineRequirePrelude } from "./inline-imports.ts";
+import { loadProgram } from "./program-loader.ts";
+
+/**
+ * Writes the source to a temporary module, imports it, and removes the file.
+ *
+ * Throws `Error` when the source imports outside the closed contract, and
+ * whatever `writeFile` throws when `os.tmpdir()` cannot take the file. Each
+ * import and validation failure of `loadProgram` passes through unchanged, so
+ * the guidance is the guidance a bad file gives. The temporary file is
+ * unlinked on each path, and a failed unlink never replaces the primary error.
+ * Removal of the file does not keep a running program from resolving a
+ * built-in module or an absolute path, so the contract is enforced by the
+ * check on the source and by the `require` prelude, not by the removal. The
+ * prelude is one line before the source, so each stack line the module
+ * reports is one below the line the caller wrote; a source that declares its
+ * own top-level `require` binding fails to load.
+ */
+export async function loadInlineProgram(source: string): Promise<OrchestrationProgram> {
+  assertClosedImports(source);
+  // A unique name per Run keeps Bun's module cache from aliasing two different
+  // Inline Programs when `main()` runs more than one time in one process.
+  const path = join(tmpdir(), `yaag-inline-${randomUUID()}.ts`);
+  await writeFile(path, `${inlineRequirePrelude()}\n${source}`, { mode: 0o600 });
+  try {
+    return await loadProgram(path);
+  } finally {
+    // The program's own error is the primary diagnostic, so a failed unlink
+    // must not replace it.
+    await unlink(path).catch(() => {});
+  }
+}

package/src/interactive-run.ts

@@ -1,8 +1,8 @@
 /**
- * The `yaag run` path that opens the alt-screen Run tree (spec §4).
+ * The `yaag run` path that opens the alt-screen Run tree (architecture §9).
  *
  * `orchestrateInteractiveRun` is process-free: every collaborator arrives as a
- * parameter, so each exit path — settle, detach, fatal render, signal — is
+ * parameter, so each exit path — settle, close, fatal render, signal — is
  * driven in tests without a TTY. `runInteractive` is the thin production edge
  * that binds it to the real terminal, the real signals, and the real streams.
  *
@@ -63,9 +63,10 @@ export interface InteractiveRunDeps {
  * exit code of the Run.
  *
  * The terminal is restored before this resolves or rejects, on every path: the
- * settle-then-`q` path, a confirmed stop, a detach, and a render throw. A
- * detach closes the alt-screen and keeps awaiting the Run on the plain lines,
- * so the process never exits with a Run still running. A fatal render error is
+ * settle-then-`esc` path, a confirmed stop, an `esc` over a live Run, and a
+ * render throw. Closing the view over a live Run closes the alt-screen and
+ * keeps awaiting the Run on the plain lines, so the process never exits with a
+ * Run still running. A fatal render error is
  * reported only after the terminal is restored and the Run is aborted and
  * reaped, so no Run is abandoned pending. A fatal accepted at any point while
  * the handlers are installed is rethrown, never converted into a normal return.
@@ -118,7 +119,7 @@ export async function orchestrateInteractiveRun(deps: InteractiveRunDeps): Promi
     }
     const settled = await running;
     app.settle(viewResult(settled));
-    // The settled view stays interactive until the reader presses `q` (spec §1).
+    // The settled view stays interactive until the reader presses `esc`.
     const exit = await Promise.race([app.exit, signal.wait]);
     let fatal = exit.kind === "fatal" ? exit : signal.taken();
     const closing = app.close();

package/src/program-loader.ts

@@ -0,0 +1,28 @@
+/**
+ * Loads an Orchestration Program module from a file.
+ *
+ * One loader keeps a file program and an Inline Program on identical guidance
+ * when a module is not a program.
+ */
+import { isOrchestrationProgram, type OrchestrationProgram } from "@yaag/runtime";
+
+/**
+ * Imports `path` and returns its default export as an Orchestration Program.
+ *
+ * The program is the module's default export, and nothing else will do.
+ * Throws what Bun throws when the module is missing, does not parse, resolves
+ * no import, or throws at its top level. Throws `Error` with the guidance
+ * `export defineRun({ run }) as the default export` when the module imports
+ * but its default export is not an Orchestration Program.
+ */
+export async function loadProgram(path: string): Promise<OrchestrationProgram> {
+  const module: unknown = await import(path);
+  const program =
+    typeof module === "object" && module !== null && "default" in module
+      ? module.default
+      : undefined;
+  if (!isOrchestrationProgram(program)) {
+    throw new Error(`${path}: export defineRun({ run }) as the default export`);
+  }
+  return program;
+}

package/src/run-invocation.ts

@@ -9,7 +9,10 @@ import type { RunOptions, StampedEventSink } from "@yaag/runtime";
 
 /** Everything `yaag run` parsed for one Run. */
 export interface RunFlags {
-  readonly programFile: string;
+  /** Absent for an Inline Program, which has no file to record (ADR-0033). */
+  readonly programFile: string | undefined;
+  /** Present only for an Inline Program; becomes the Run's recorded identity (ADR-0033). */
+  readonly programSource: string | undefined;
   readonly args: unknown;
   readonly eventsFd: number | undefined;
   readonly record: string | undefined;
@@ -27,7 +30,8 @@ export function executeOptions(
   return {
     events,
     args: flags.args,
-    programFile: flags.programFile,
+    ...(flags.programFile === undefined ? {} : { programFile: flags.programFile }),
+    ...(flags.programSource === undefined ? {} : { programSource: flags.programSource }),
     ...(flags.record === undefined ? {} : { record: flags.record }),
     ...(flags.replay === undefined ? {} : { replay: flags.replay }),
     ...(flags.resume === undefined ? {} : { resume: flags.resume }),

package/src/run-program.ts

@@ -0,0 +1,46 @@
+/**
+ * Composes the two ways `yaag run` gets its Orchestration Program: a file, or
+ * the source text of an Inline Program.
+ *
+ * The composition sits above both loaders, so neither loader knows the other
+ * and the imports stay a DAG.
+ */
+import { resolve } from "node:path";
+import type { OrchestrationProgram } from "@yaag/runtime";
+import type { ProgramSource } from "./argv.ts";
+import { loadInlineProgram } from "./inline-program.ts";
+import { loadProgram } from "./program-loader.ts";
+
+/** What one Run loaded. An Inline Program has no program file (ADR-0033). */
+export interface LoadedProgram {
+  readonly program: OrchestrationProgram;
+  readonly programFile: string | undefined;
+  /** Present only for an Inline Program: its source is the Run's identity (ADR-0033). */
+  readonly programSource: string | undefined;
+}
+
+/**
+ * Loads the program a `run` invocation names, from a file or from source text.
+ *
+ * A file path is resolved against the working directory, and its
+ * `programFile` is that absolute path. An Inline Program reports no
+ * `programFile`, because its temporary module is unlinked after the import; it
+ * reports its source text as its identity instead.
+ * Each failure of `loadProgram` or `loadInlineProgram` — a missing file, a
+ * specifier outside the closed contract, a module that is not a program —
+ * passes through unchanged.
+ */
+export async function loadRunProgram(source: ProgramSource): Promise<LoadedProgram> {
+  switch (source.kind) {
+    case "file": {
+      const programFile = resolve(source.file);
+      return { program: await loadProgram(programFile), programFile, programSource: undefined };
+    }
+    case "inline":
+      return {
+        program: await loadInlineProgram(source.source),
+        programFile: undefined,
+        programSource: source.source,
+      };
+  }
+}

package/src/tree-app.ts

@@ -1,6 +1,6 @@
 /**
  * The standalone CLI's interactive Run view: the same `@yaag/tui` tree the Host
- * Session opens, hosted in an alt-screen pi-tui app (spec §4).
+ * Session opens, hosted in an alt-screen pi-tui app (architecture §9).
  *
  * Every collaborator arrives as a parameter, so the app is driven in tests over
  * a recording terminal; `alt-screen.ts` owns the real `ProcessTerminal`.
@@ -28,7 +28,6 @@ export interface TreeAppDeps {
 /** How the app ended. A fatal exit still restored the terminal. */
 export type TreeAppExit =
   | { readonly kind: "dismissed" }
-  | { readonly kind: "detached" }
   | { readonly kind: "fatal"; readonly error: unknown };
 
 /** What `finish` writes after the alt-screen closes (architecture §9). */
@@ -43,7 +42,7 @@ export interface FinalOutput {
 export interface TreeApp {
   /** The projection the view reads; the caller renders the final frame from it. */
   readonly state: TreeState;
-  /** Resolves when the reader dismisses or detaches, or a render throws. */
+  /** Resolves when the reader closes the view, or a render throws. */
   readonly exit: Promise<TreeAppExit>;
   /** Folds one Lifecycle Event into the projection and redraws. */
   present(event: LifecycleEvent): void;
@@ -54,7 +53,7 @@ export interface TreeApp {
   /**
    * Drains input and leaves the alt-screen, writing no channel. Once.
    *
-   * A detach closes the alt-screen while the Run is still live, so this step is
+   * `esc` closes the alt-screen while the Run is still live, so this step is
    * separate from the final channel emission.
    */
   close(): Promise<void>;
@@ -98,13 +97,11 @@ export function startTreeApp(deps: TreeAppDeps): TreeApp {
     host: {
       ...host,
       stop: deps.stop,
-      // A CLI has no background surface, so a detach closes the alt-screen and
-      // the caller keeps awaiting the Run on the plain line presenter.
-      detach: () => resolveExit({ kind: "detached" }),
-      done: (kind) => resolveExit({ kind: kind === "detached" ? "detached" : "dismissed" }),
+      // A CLI has no background surface, so closing the view closes the
+      // alt-screen and the caller keeps awaiting the Run on the plain lines.
+      done: () => resolveExit({ kind: "dismissed" }),
     },
     ...(deps.label === undefined ? {} : { label: deps.label }),
-    surface: "foreground",
     ...(deps.now === undefined ? {} : { now: deps.now }),
   });