@nicknisi/pi-workflows 0.1.0

package/dist/workflow.test.js

@@ -0,0 +1,299 @@
+/**
+ * Tests for the workflow engine (pi-free) and saved-workflow discovery.
+ *
+ * Style follows packages/shared/subagents.test.ts: a fake spawn with no real
+ * child sessions, and tmp dirs for filesystem discovery. The vm/parallel/
+ * pipeline/args/budget coverage exercises engine.ts directly; discovery
+ * coverage imports listWorkflows/findWorkflowFile from index.ts and points
+ * PI_CODING_AGENT_DIR at a tmp dir so getAgentDir() resolves there.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { runScript } from './engine.js';
+const tmpdirs = [];
+function tmpRoot() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-workflows-test-'));
+    tmpdirs.push(dir);
+    return dir;
+}
+afterEach(() => {
+    for (const dir of tmpdirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+// ── Fake spawn ─────────────────────────────────────────────────────────────
+// Echoes the prompt as text; carries a fixed token cost so budget accounting
+// is observable. An `impl` override lets individual cases craft outcomes.
+function fakeSpawn(impl) {
+    return async (opts) => impl
+        ? impl(opts)
+        : {
+            ok: true,
+            text: `echo: ${opts.prompt}`,
+            usage: { inputTokens: 10, outputTokens: 5, totalTokens: 15 },
+        };
+}
+function fakeFail(kind, error) {
+    return async () => ({
+        ok: false,
+        kind,
+        error,
+        text: '',
+        usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+    });
+}
+describe('engine: meta export + vm compile', () => {
+    it('strips `export const meta =` and surfaces meta.name/description', async () => {
+        const r = await runScript({
+            script: "export const meta = { name: 'demo', description: 'a demo' };\nreturn meta.name;",
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.meta?.name).toBe('demo');
+        expect(r.meta?.description).toBe('a demo');
+        expect(r.value).toBe('demo');
+    });
+    it('compiles a top-level return (wrapped in an async function)', async () => {
+        const r = await runScript({
+            script: 'const x = 21; return x * 2;',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toBe(42);
+        expect(r.meta).toBeUndefined();
+    });
+    it('returns undefined when the script forgets to return', async () => {
+        const r = await runScript({
+            script: 'const x = 1;',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toBeUndefined();
+    });
+    it('multi-line meta object is captured whole', async () => {
+        const r = await runScript({
+            script: [
+                'export const meta = {',
+                "  name: 'lanes',",
+                "  description: 'parallel lanes',",
+                '  phases: [{ title: "Execute" }],',
+                '};',
+                'return meta.phases.length;',
+            ].join('\n'),
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.meta?.name).toBe('lanes');
+        expect(r.meta?.phases).toEqual([{ title: 'Execute' }]);
+        expect(r.value).toBe(1);
+    });
+});
+describe('engine: parallel + pipeline', () => {
+    it('parallel awaits Promise.all over zero-arg thunks', async () => {
+        const r = await runScript({
+            script: 'const r = await parallel([() => agent("a"), () => agent("b")]); return r;',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toEqual(['echo: a', 'echo: b']);
+    });
+    it('pipeline folds items through stages in parallel waves', async () => {
+        const r = await runScript({
+            script: 'const out = await pipeline([1, 2], async (n) => n * 2, async (n) => n + 1); return out;',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toEqual([3, 5]);
+    });
+    it('pipeline with zero items returns an empty array (no stranded stage)', async () => {
+        const r = await runScript({
+            script: 'const out = await pipeline([], async (n) => n); return out;',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toEqual([]);
+    });
+});
+describe('engine: args + budget + log/phase', () => {
+    it('passes args through as a global', async () => {
+        const r = await runScript({
+            script: 'return args.projectName;',
+            args: { projectName: 'foo', phases: [] },
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toBe('foo');
+    });
+    it('budget.spent accumulates over agent() calls', async () => {
+        const r = await runScript({
+            script: 'await agent("x"); await agent("y"); return budget.spent;',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toBe(30);
+        expect(r.usage.totalTokens).toBe(30);
+        expect(r.usage.inputTokens).toBe(20);
+    });
+    it('budget.total defaults to Infinity and remaining tracks spent', async () => {
+        const r = await runScript({
+            script: 'await agent("x"); return { total: budget.total, remaining: budget.remaining };',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toEqual({ total: Infinity, remaining: Infinity });
+    });
+    it('budget.total honors a configured cap', async () => {
+        const r = await runScript({
+            script: 'return { total: budget.total, remaining: budget.remaining };',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+            budgetTotal: 1000,
+        });
+        expect(r.value).toEqual({ total: 1000, remaining: 1000 });
+    });
+    it('log and phase capture into the result logs', async () => {
+        const r = await runScript({
+            script: 'phase("Wave 1"); log("hello", { k: 1 }); return "done";',
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.logs).toContain('── Wave 1');
+        expect(r.logs.some((l) => l.startsWith('hello'))).toBe(true);
+    });
+});
+describe('engine: agent opts + failures', () => {
+    it('agentType is accepted but ignored (logged), no registry', async () => {
+        const r = await runScript({
+            script: "await agent('x', { agentType: 'scout' }); return 'ok';",
+            spawn: fakeSpawn(),
+            cwd: '/tmp',
+        });
+        expect(r.value).toBe('ok');
+        expect(r.logs.some((l) => l.includes("agentType 'scout'"))).toBe(true);
+    });
+    it('label maps to the spawn agent label', async () => {
+        let seen;
+        const spawn = async (opts) => {
+            seen = opts.agent;
+            return { ok: true, text: 'ok', usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } };
+        };
+        await runScript({
+            script: "await agent('x', { label: 'reviewer' }); return 'ok';",
+            spawn,
+            cwd: '/tmp',
+        });
+        expect(seen).toBe('reviewer');
+    });
+    it('defaults children to read-only tools when tools omitted', async () => {
+        let seen;
+        const spawn = async (opts) => {
+            seen = opts.tools;
+            return { ok: true, text: 'ok', usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 } };
+        };
+        await runScript({
+            script: "await agent('x'); return 'ok';",
+            spawn,
+            cwd: '/tmp',
+        });
+        expect(seen).toEqual(['read', 'grep', 'find', 'ls']);
+    });
+    it('agent failure throws `${kind}: ${error}`', async () => {
+        const r = await runScript({
+            script: 'try { await agent("x"); } catch (e) { return e.message; }',
+            spawn: fakeFail('crashed', 'boom'),
+            cwd: '/tmp',
+        });
+        expect(r.value).toBe('crashed: boom');
+    });
+    it('agent returns res.data when a schema/data payload is present', async () => {
+        const spawn = async () => ({
+            ok: true,
+            text: '{"verdict":"PASS"}',
+            data: { verdict: 'PASS' },
+            usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+        });
+        const r = await runScript({
+            script: 'const v = await agent("x"); return v.verdict;',
+            spawn,
+            cwd: '/tmp',
+        });
+        expect(r.value).toBe('PASS');
+    });
+});
+// ── Saved-workflow discovery ───────────────────────────────────────────────
+describe('saved-workflow discovery', () => {
+    let prevAgentDir;
+    let agentDir;
+    let projectDir;
+    beforeEach(() => {
+        prevAgentDir = process.env.PI_CODING_AGENT_DIR;
+        agentDir = tmpRoot();
+        projectDir = tmpRoot();
+        process.env.PI_CODING_AGENT_DIR = agentDir;
+    });
+    afterEach(() => {
+        if (prevAgentDir === undefined)
+            delete process.env.PI_CODING_AGENT_DIR;
+        else
+            process.env.PI_CODING_AGENT_DIR = prevAgentDir;
+    });
+    // Imported lazily so PI_CODING_AGENT_DIR is set before getAgentDir() is
+    // called. index.ts reads getAgentDir() at call time inside workflowDirs,
+    // not at module load, so this resolves to the tmp agentDir.
+    async function loadDiscovery() {
+        const mod = await import('./index.js');
+        return { listWorkflows: mod.listWorkflows, findWorkflowFile: mod.findWorkflowFile };
+    }
+    it('lists global workflows from ~/.pi/agent/workflows', async () => {
+        const { listWorkflows } = await loadDiscovery();
+        const dir = path.join(agentDir, 'workflows');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'research.js'), "export const meta = { name: 'research', description: 'parallel research' };\nreturn 'ok';");
+        fs.writeFileSync(path.join(dir, 'empty.js'), '// no meta\nreturn 1;');
+        const items = listWorkflows(projectDir, false);
+        expect(items.map((i) => i.name).sort()).toEqual(['empty', 'research']);
+        const research = items.find((i) => i.name === 'research');
+        expect(research.scope).toBe('global');
+        expect(research.description).toBe('parallel research');
+    });
+    it('finds a workflow file by name (global)', async () => {
+        const { findWorkflowFile } = await loadDiscovery();
+        const dir = path.join(agentDir, 'workflows');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'demo.js'), 'return 1;');
+        expect(findWorkflowFile('demo', projectDir, false)).toBe(path.join(dir, 'demo.js'));
+    });
+    it('project workflows are visible only when trusted', async () => {
+        const { listWorkflows, findWorkflowFile } = await loadDiscovery();
+        const dir = path.join(projectDir, '.pi', 'workflows');
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, 'secret.js'), 'return 1;');
+        expect(listWorkflows(projectDir, false).find((i) => i.name === 'secret')).toBeUndefined();
+        expect(findWorkflowFile('secret', projectDir, false)).toBeUndefined();
+        expect(listWorkflows(projectDir, true).find((i) => i.name === 'secret')?.scope).toBe('project');
+        expect(findWorkflowFile('secret', projectDir, true)).toBe(path.join(dir, 'secret.js'));
+    });
+    it('global shadows a same-named project workflow', async () => {
+        const { listWorkflows } = await loadDiscovery();
+        const gDir = path.join(agentDir, 'workflows');
+        const pDir = path.join(projectDir, '.pi', 'workflows');
+        fs.mkdirSync(gDir, { recursive: true });
+        fs.mkdirSync(pDir, { recursive: true });
+        fs.writeFileSync(path.join(gDir, 'dup.js'), 'return 1;');
+        fs.writeFileSync(path.join(pDir, 'dup.js'), 'return 2;');
+        const items = listWorkflows(projectDir, true);
+        expect(items.filter((i) => i.name === 'dup')).toHaveLength(1);
+        expect(items.find((i) => i.name === 'dup')?.scope).toBe('global');
+    });
+    it('rejects path-like names (no escaping the workflows dirs)', async () => {
+        const { findWorkflowFile } = await loadDiscovery();
+        expect(findWorkflowFile('..', projectDir, true)).toBeUndefined();
+        expect(findWorkflowFile('../etc/passwd', projectDir, true)).toBeUndefined();
+        expect(findWorkflowFile('a/b', projectDir, true)).toBeUndefined();
+    });
+    it('returns empty list when no dirs exist', async () => {
+        const { listWorkflows } = await loadDiscovery();
+        expect(listWorkflows(projectDir, true)).toEqual([]);
+    });
+});

package/engine.ts

@@ -0,0 +1,295 @@
+/**
+ * The workflow script engine — pi-free and testable.
+ *
+ * A workflow script is a JavaScript statement body with injected globals
+ * (args, agent, parallel, pipeline, phase, log, budget, cwd) and a leading
+ * `export const meta = { name, description }` declaration. It returns a value
+ * by evaluating a trailing expression or a top-level `return` (the body is
+ * wrapped in an async function so a bare `return` compiles).
+ *
+ * This module deliberately imports nothing from pi or @nicknisi/pi-shared so
+ * the test suite can exercise it without an install step: the spawn function
+ * is injected. index.ts wires it to the shared subagent runtime.
+ *
+ * The compile model mirrors ~/Developer/ideation/workflows/engine-host.mjs:
+ * `export const meta =` is rewritten to an outer-binding assignment so the vm
+ * compiles (a stranded `export` fails loudly) and the tool can surface
+ * meta.name/description.
+ */
+
+import vm from 'node:vm';
+
+// ── Public types ───────────────────────────────────────────────────────────
+
+export interface EngineSpawnUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cost?: number | undefined;
+}
+
+export interface EngineSpawnOk {
+  ok: true;
+  text: string;
+  data?: unknown;
+  usage: EngineSpawnUsage;
+  /** Run id of the child spawn, when the spawn fn attaches it. */
+  runId?: string;
+  /** Path to the worktree `.patch` file, for `worktree: true` runs that changed files. */
+  patchPath?: string;
+}
+
+export interface EngineSpawnFail {
+  ok: false;
+  kind: string;
+  error: string;
+  text: string;
+  usage: EngineSpawnUsage;
+}
+
+export type EngineSpawnResult = EngineSpawnOk | EngineSpawnFail;
+
+export interface EngineSpawnOptions {
+  prompt: string;
+  agent?: string;
+  model?: string;
+  tools?: string[];
+  systemPrompt?: string;
+  thinkingLevel?: string;
+  timeoutMs?: number;
+  maxTurns?: number;
+  outputSchema?: unknown;
+  /** Run the child in an isolated git worktree; its change set is captured to a `.patch`. */
+  worktree?: boolean;
+}
+
+export type EngineSpawnFn = (opts: EngineSpawnOptions) => Promise<EngineSpawnResult>;
+
+export interface EngineBudget {
+  total: number;
+  spent: number;
+  remaining: number;
+}
+
+export interface ScriptMeta {
+  name?: string;
+  description?: string;
+  [k: string]: unknown;
+}
+
+export interface RunScriptOptions {
+  script: string;
+  args?: unknown;
+  spawn: EngineSpawnFn;
+  cwd: string;
+  budgetTotal?: number;
+  onLog?: (line: string) => void;
+}
+
+export interface RunScriptResult {
+  value: unknown;
+  meta: ScriptMeta | undefined;
+  logs: string[];
+  usage: EngineSpawnUsage;
+  durationMs: number;
+}
+
+// ── Internals ──────────────────────────────────────────────────────────────
+
+const STRIP_META = /export\s+const\s+meta\s*=/;
+const DEFAULT_TOOLS = ['read', 'grep', 'find', 'ls'];
+const MAX_LOG_ENTRIES = 200;
+const MAX_LOG_CHARS = 2000;
+
+function truncate(line: string, max: number): string {
+  return line.length <= max ? line : `${line.slice(0, max)}…[truncated at ${max} chars]`;
+}
+
+function safeStringify(v: unknown): string {
+  if (typeof v === 'string') return v;
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}
+
+function zeroUsage(): EngineSpawnUsage {
+  return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+}
+
+function addUsage(a: EngineSpawnUsage, b: EngineSpawnUsage): void {
+  a.inputTokens += b.inputTokens;
+  a.outputTokens += b.outputTokens;
+  a.totalTokens += b.totalTokens;
+  if (b.cost !== undefined) a.cost = (a.cost ?? 0) + b.cost;
+}
+
+// ── Engine ─────────────────────────────────────────────────────────────────
+
+export async function runScript(opts: RunScriptOptions): Promise<RunScriptResult> {
+  const { script, spawn, cwd } = opts;
+  const args = opts.args;
+  const budgetTotal = opts.budgetTotal ?? Infinity;
+  const logs: string[] = [];
+  const usage = zeroUsage();
+  const startedAt = Date.now();
+
+  const log = (...parts: unknown[]): void => {
+    if (logs.length >= MAX_LOG_ENTRIES) return;
+    const line = parts.map(safeStringify).join(' ');
+    const t = truncate(line, MAX_LOG_CHARS);
+    logs.push(t);
+    opts.onLog?.(t);
+  };
+
+  const phase = (name: string): void => {
+    const line = `── ${name}`;
+    logs.push(line);
+    opts.onLog?.(line);
+  };
+
+  const budget: EngineBudget = {
+    get total() {
+      return budgetTotal;
+    },
+    get spent() {
+      return usage.totalTokens;
+    },
+    get remaining() {
+      return budgetTotal - usage.totalTokens;
+    },
+  };
+
+  // agent(prompt, opts) backed by the injected spawn. A failure kind becomes
+  // a throw so a script's safeAgent wrapper converts it into a typed stage
+  // failure (matching ~/Developer/ideation/workflows/engine-host.mjs).
+  const agent = async (prompt: string, agentOpts: Record<string, unknown> = {}): Promise<unknown> => {
+    if (typeof agentOpts.agentType === 'string') {
+      log(`(agentType '${agentOpts.agentType}' accepted but ignored — no agent-type registry)`);
+    }
+    const spawnOpts: EngineSpawnOptions = {
+      prompt,
+      ...(typeof agentOpts.label === 'string' ? { agent: agentOpts.label } : {}),
+      ...(typeof agentOpts.model === 'string' ? { model: agentOpts.model } : {}),
+      ...(Array.isArray(agentOpts.tools) ? { tools: agentOpts.tools as string[] } : { tools: DEFAULT_TOOLS }),
+      ...(typeof agentOpts.systemPrompt === 'string' ? { systemPrompt: agentOpts.systemPrompt } : {}),
+      ...(typeof agentOpts.effort === 'string' ? { thinkingLevel: agentOpts.effort } : {}),
+      ...(typeof agentOpts.timeoutMs === 'number' ? { timeoutMs: agentOpts.timeoutMs } : {}),
+      ...(typeof agentOpts.maxTurns === 'number' ? { maxTurns: agentOpts.maxTurns } : {}),
+      ...(agentOpts.schema !== undefined ? { outputSchema: agentOpts.schema } : {}),
+      ...(agentOpts.worktree === true ? { worktree: true } : {}),
+    };
+    const res = await spawn(spawnOpts);
+    addUsage(usage, res.usage);
+    if (!res.ok) throw new Error(`${res.kind}: ${res.error}`);
+    // A worktree run that changed files produces a `.patch`; surface it
+    // alongside the value so the script can hand the path to a judge or
+    // return it for the `/patches` apply flow. Opt-in: only when patchPath is
+    // present, so non-worktree scripts see the unchanged `data ?? text` return.
+    if (res.patchPath) return { value: res.data ?? res.text ?? null, patchPath: res.patchPath, runId: res.runId };
+    return res.data ?? res.text ?? null;
+  };
+
+  const parallel = <T>(thunks: Array<() => Promise<T>>): Promise<T[]> => Promise.all(thunks.map((t) => t()));
+
+  // pipeline(items, ...stages): each stage maps over the previous stage's
+  // outputs in parallel, producing the next array. A fold over Promise.all.
+  const pipeline = async <T, U>(items: T[], ...stages: Array<(item: T, index: number) => Promise<U>>): Promise<U[]> => {
+    let values: unknown[] = [...items];
+    for (const stage of stages) {
+      values = await parallel((values as T[]).map((v, i) => () => stage(v, i)));
+    }
+    return values as U[];
+  };
+
+  // Compile + run. compileScript is extracted so callers (tests, future
+  // tooling) can compile + read `meta` without a real spawn.
+  const compiled = compileScript(script);
+  const value = await compiled.fn(args, agent, parallel, pipeline, phase, log, budget, cwd);
+  return { value, meta: compiled.meta, logs, usage, durationMs: Date.now() - startedAt };
+}
+
+// ── Compile-only entry ────────────────────────────────────────────────────
+
+/** The compiled async body; invoking it runs the script with injected globals. */
+export type CompiledFn = (
+  args: unknown,
+  agent: unknown,
+  parallel: unknown,
+  pipeline: unknown,
+  phase: unknown,
+  log: unknown,
+  budget: unknown,
+  cwd: string,
+) => Promise<unknown>;
+
+export interface CompiledScript {
+  /** The script's `meta` export, read via a stub dry-run (no real spawn). */
+  meta: ScriptMeta | undefined;
+  /** Invoke to run the script; spawn-backed globals must be supplied. */
+  fn: CompiledFn;
+}
+
+/**
+ * Compile a workflow script and read its `meta` export WITHOUT a real spawn.
+ *
+ * `export const meta =` is rewritten to an outer-binding assignment so the vm
+ * compiles (a stranded `export` fails loudly) and `meta` is captured into a
+ * holder. The body is wrapped in an async function so a top-level `return`
+ * compiles. `meta` is populated by a stub dry-run — `agent` returns `null`,
+ * `parallel`/`pipeline` are `Promise.all`-style folds over those stubs — so the
+ * script's `meta` declaration (which well-formed scripts place first) is read
+ * without spawning any child sessions. A syntax error throws here.
+ */
+export function compileScript(script: string): CompiledScript {
+  const metaHolder: { value: ScriptMeta | undefined } = { value: undefined };
+  const stripped = script.replace(STRIP_META, 'const meta = metaHolder.value =');
+  const wrapped = `(async function(args, agent, parallel, pipeline, phase, log, budget, cwd, metaHolder){\n${stripped}\n})`;
+  const raw = new vm.Script(wrapped, { filename: 'workflow.js' }).runInThisContext() as (
+    args: unknown,
+    agent: unknown,
+    parallel: unknown,
+    pipeline: unknown,
+    phase: unknown,
+    log: unknown,
+    budget: unknown,
+    cwd: string,
+    metaHolder: { value: ScriptMeta | undefined },
+  ) => Promise<unknown>;
+  // Bind metaHolder so callers invoke an 8-arg fn; the holder rides the call
+  // (runInThisContext cannot see a closure variable, so it must be a parameter).
+  const fn: CompiledFn = (args, agent, parallel, pipeline, phase, log, budget, cwd) =>
+    raw(args, agent, parallel, pipeline, phase, log, budget, cwd, metaHolder);
+
+  // Stub dry-run to read `meta`. Well-formed scripts declare `meta` first, so
+  // it is assigned synchronously before the first `await`; we await the whole
+  // stubbed body anyway so a script that computes meta from `args` works too.
+  // Any throw is swallowed — we only care that it compiled + set meta.
+  const stubAgent = async (): Promise<null> => null;
+  const stubParallel = <T>(thunks: Array<() => Promise<T>>): Promise<T[]> => Promise.all(thunks.map((t) => t()));
+  const stubPipeline = async <T, U>(items: T[], ...stages: Array<(item: T) => Promise<U>>): Promise<U[]> => {
+    let values: unknown[] = [...items];
+    for (const stage of stages) values = await stubParallel((values as T[]).map((v) => () => stage(v)));
+    return values as U[];
+  };
+  const stubBudget = { total: Infinity, spent: 0, remaining: Infinity };
+  void fn(
+    undefined,
+    stubAgent,
+    stubParallel,
+    stubPipeline,
+    () => {},
+    () => {},
+    stubBudget,
+    '/tmp',
+  ).catch(() => {});
+
+  // `meta` is a getter so a caller that re-runs `fn` with real globals sees
+  // the post-run meta (the stub dry-run may have thrown on args-derived meta;
+  // the real run sets it). For static meta the stub already populated it.
+  return Object.defineProperty({ fn }, 'meta', {
+    get: () => metaHolder.value,
+    enumerable: true,
+  }) as CompiledScript;
+}