willfire 0.1.10 → 0.1.11

package/README.md

@@ -54,8 +54,9 @@ workflows all applied. That is the unit required status checks key on, so it
 is the one worth comparing against. On a `JobEntry` it is `null` only where no
 single name is knowable ahead of the run:
 
-- a matrix computed at runtime (`fromJSON` of another job's output), reported
-  as one `unknown` entry for that job and nothing else;
+- a matrix computed at runtime (`fromJSON` of another job's output) whose
+  outputs were not supplied, reported as one `unknown` entry for that job and
+  nothing else — see "Supplying job outputs" below;
 - a reusable workflow we cannot read — private, deleted, a ref that does not
   exist, a `uses:` built from an expression, or one nested past GitHub's
   four-level limit;
@@ -83,7 +84,8 @@ Auth is any token with `contents: read`, `actions: read`, and
 
 ```sh
 GH_TOKEN=... willfire --repo owner/repo --pr 123 \
-  [--action opened|synchronize|reopened] [--json]
+  [--action opened|synchronize|reopened] [--json] \
+  [--execute owner/repo:job1,job2]...
 ```
 
 Plain-text output is one line per entry, then a `# read owner/repo@ref -> sha`
@@ -100,8 +102,87 @@ workflows — both the local `./.github/workflows/x.yml` form and the cross-repo
 commit and the callee then read at that commit. Jobs whose `if` is false are
 predicted as `skipped` entries, matching how they appear in the checks UI.
 
-Things that cannot be known statically — e.g. a matrix computed at runtime
-from another job's output — are reported as `unknown` rather than guessed.
+Things that cannot be known statically are reported as `unknown` rather than
+guessed.
+
+## Supplying job outputs
+
+A matrix built from another job's output is the common way a workflow decides
+its own check names:
+
+```yaml
+strategy:
+  matrix:
+    language: ${{ fromJSON(needs.detect.outputs.coverage_languages) }}
+```
+
+Given those outputs, willfire expands it. `expandWorkflowJobs` takes a `scope`
+whose `needs` maps a job id to its outputs:
+
+```ts
+await expandWorkflowJobs(wf, ctx, fetchWorkflow, source, {
+  needs: { detect: { outputs: { coverage_languages: '["typescript"]' } } },
+});
+```
+
+Values are raw strings — what a step wrote to `$GITHUB_OUTPUT`, and what the
+runner substitutes. Parsing them here would break the guards written against
+them: `!= '[]'` compares a string to a string, and an array on the left makes
+it unknown. `fromJSON` is the only thing that turns one into a structure.
+
+`outputs` must be the job's *complete* output set, because a key absent from it
+reads as the empty string — the same answer the runner gives for an output no
+step wrote. A job you know nothing about belongs left out entirely; every
+lookup against it then stays unknown.
+
+`needs` is workflow-scoped and is not inherited across a reusable-workflow
+call: a callee's `needs.detect` is the callee's own job.
+
+Nothing in willfire works out what those outputs are on its own. `predict`
+supplies none unless the caller grants execution — see below — so a dynamic
+matrix stays `unknown` by default.
+
+## Executing granted jobs
+
+The job those outputs come from is usually a few shell steps over the checked
+out tree — cheap to run for real. `predict` will do that, but only for jobs
+the caller names:
+
+```ts
+await predict(octokit, "owner/repo", 123, {
+  execute: [{ repo: "the-org/conventions", jobs: ["detect"] }],
+});
+```
+
+```sh
+willfire --repo owner/repo --pr 123 \
+  --execute the-org/conventions:detect
+```
+
+A grant names the repo the workflow *file* lives in — for a reusable workflow,
+the callee — and the job ids within it. Before expansion reads `needs`, each
+granted job that is predicted to run is executed: the PR's head tree is
+materialized from a tarball, the job's steps run in order under their declared
+shell and env, step-level `if:` guards are evaluated, composite actions are
+fetched at their pinned commit and recursed into, and a bare
+`actions/checkout` is satisfied by the tree already present. What the steps
+write to `$GITHUB_OUTPUT` becomes the job's outputs, exactly as if they had
+been supplied by hand.
+
+Execution is mechanism, not policy: willfire knows nothing about any repo, and
+with no grants nothing runs. The steps execute for real — nothing interprets
+or approximates shell — so grant only jobs whose code you trust at the commit
+being predicted; a granted job runs the PR's version of itself.
+
+Anything execution cannot do faithfully fails the grant rather than guessing:
+a JavaScript or Docker action, a checkout with inputs, a matrix'd or
+containerized granted job, an undecidable step `if:`, a non-zero exit, output
+willfire cannot parse. The failure does not change any verdict — entries that
+needed the outputs stay `unknown`, with the reason threaded through:
+
+```
+dynamic matrix; executing 'detect' failed: step 'scan': exited 1 (...)
+```
 
 ## Development
 

package/dist/execute.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Execute a job the caller granted, to learn what static reading cannot.
+ *
+ * A dynamic matrix — `language: ${{ fromJSON(needs.detect.outputs.x) }}` — is
+ * the values another job computes at runtime. No amount of reading the YAML
+ * yields them; the fleet's `detect` job runs a script over the repo tree and
+ * writes what it finds to `$GITHUB_OUTPUT`. So this module runs that job the
+ * way the runner would: materialize the tree at the pinned commit, walk the
+ * steps in order, execute each `run:` under its declared shell and env, and
+ * assemble the job's `outputs:` map from what the steps actually wrote.
+ *
+ * Three rules keep this honest:
+ *
+ * 1. **Nothing runs without a grant.** willfire has no opinion about which
+ *    jobs are safe to execute; the caller names them, one repo and job id at
+ *    a time, and everything else stays as unresolved as it was.
+ * 2. **Run it, never interpret it.** The `run:` script is handed to the shell
+ *    the step declares, with the env it declares. What lands in
+ *    `$GITHUB_OUTPUT` is the answer; no shell text is ever parsed for meaning.
+ * 3. **Anything off the modelled path is a hard stop with a reason.** A
+ *    JavaScript action, an undecidable `if:`, a `${{ }}` that will not
+ *    resolve, a step that exits non-zero — each fails the execution and says
+ *    what it hit, and the consumers of that job's outputs stay unresolved.
+ *    Guessing is the one move this module never makes.
+ *
+ * `actions/checkout` is the deliberate exception to rule 2. It is provided by
+ * the runner, not run from its repo, and its whole postcondition — the
+ * workspace tree at the commit under test — is something the executor has
+ * already satisfied by materializing the tree. A bare checkout is therefore
+ * recorded as done; a checkout *with inputs* is not modelled and stops.
+ */
+import { type Scope } from "./expr.js";
+import type { ResolveRef, WorkflowSource } from "./predict.js";
+/**
+ * Permission to execute named jobs from one repo's workflows.
+ *
+ * `repo` is the repo the *workflow file* lives in — for a fleet consumer
+ * calling `testing-conventions/.github/workflows/testing-conventions.yml@v0`,
+ * that is `thekevinscott/testing-conventions`, whatever repo the PR is on.
+ * The grant is deliberately this narrow: a job id alone would execute
+ * whatever any transitively-reached workflow happens to call by that name.
+ */
+export interface ExecutionGrant {
+    /** `owner/name` of the repo whose workflow defines the jobs. */
+    repo: string;
+    /** Job ids within that repo's workflows that may be executed. */
+    jobs: string[];
+}
+/** `owner/repo:job1,job2` as the CLI spells a grant. */
+export declare function parseGrant(spec: string): ExecutionGrant | null;
+/** One shell invocation, fully specified — nothing is inherited implicitly. */
+export interface RunSpec {
+    script: string;
+    shell: "bash" | "sh";
+    cwd: string;
+    env: Record<string, string>;
+}
+export interface RunResult {
+    code: number;
+    /** Captured so a failing step can say *why* in its reason. */
+    stderr: string;
+}
+export type RunCommand = (spec: RunSpec) => Promise<RunResult>;
+/**
+ * Materialize a repo tree at a commit and return its root directory, or null
+ * when it cannot be had. Must not throw.
+ */
+export type ProvideTree = (source: WorkflowSource) => Promise<string | null>;
+/** The three reaches into the world an execution needs, bundled for injection. */
+export interface ExecDeps {
+    provideTree: ProvideTree;
+    runCommand: RunCommand;
+    resolveRef: ResolveRef;
+}
+export type ExecOutcome = {
+    ok: true;
+    outputs: Record<string, string>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * What expansion asks of an executor. The caller decides *whether* a job
+ * runs with its own scope — the executor only decides what running it
+ * yields. Step-level guards inside the job are evaluated here, against the
+ * fixed facts of the run (notably `github.repository`, which the fleet's
+ * hermetic-vs-published guards are written against).
+ */
+export interface JobExecutor {
+    granted(source: WorkflowSource, jobId: string): boolean;
+    executeJob(jobId: string, job: any, wf: any, scope: Scope): Promise<ExecOutcome>;
+}
+/**
+ * The `$GITHUB_OUTPUT` file format: `name=value` lines, or a
+ * `name<<DELIMITER … DELIMITER` heredoc for multi-line values. Anything else
+ * fails the parse — the runner fails the step on a malformed line, so
+ * tolerating one here would invent outputs a real run never had.
+ */
+export declare function parseGithubOutput(text: string): Record<string, string> | null;
+export declare function makeExecutor(opts: {
+    grants: ExecutionGrant[];
+    /**
+     * The PR's own repo at the head commit — what `actions/checkout` provides
+     * on a real runner, wherever the workflow file itself lives. A reusable
+     * workflow's jobs run in the caller's workspace; this is that fact.
+     */
+    workspace: WorkflowSource;
+    deps: ExecDeps;
+}): JobExecutor;
+/**
+ * The runner's default shell invocations, faithfully: `bash --noprofile
+ * --norc -e -o pipefail` and `sh -e`. Nothing of the parent environment
+ * leaks in beyond what the spec names.
+ */
+export declare const runShell: RunCommand;
+/**
+ * Materialize repo trees from tarballs, one download per commit however many
+ * steps ask. GitHub's tarballs wrap the tree in a single
+ * `owner-repo-shortsha/` directory, which is unwrapped so callers get the
+ * tree root itself. Extraction shells out to `tar` through the same
+ * `RunCommand` seam every other subprocess uses.
+ */
+export declare function makeTreeProvider(download: (source: WorkflowSource) => Promise<Uint8Array | null>, runCommand: RunCommand): ProvideTree;

package/dist/execute.js

@@ -0,0 +1,490 @@
+/**
+ * Execute a job the caller granted, to learn what static reading cannot.
+ *
+ * A dynamic matrix — `language: ${{ fromJSON(needs.detect.outputs.x) }}` — is
+ * the values another job computes at runtime. No amount of reading the YAML
+ * yields them; the fleet's `detect` job runs a script over the repo tree and
+ * writes what it finds to `$GITHUB_OUTPUT`. So this module runs that job the
+ * way the runner would: materialize the tree at the pinned commit, walk the
+ * steps in order, execute each `run:` under its declared shell and env, and
+ * assemble the job's `outputs:` map from what the steps actually wrote.
+ *
+ * Three rules keep this honest:
+ *
+ * 1. **Nothing runs without a grant.** willfire has no opinion about which
+ *    jobs are safe to execute; the caller names them, one repo and job id at
+ *    a time, and everything else stays as unresolved as it was.
+ * 2. **Run it, never interpret it.** The `run:` script is handed to the shell
+ *    the step declares, with the env it declares. What lands in
+ *    `$GITHUB_OUTPUT` is the answer; no shell text is ever parsed for meaning.
+ * 3. **Anything off the modelled path is a hard stop with a reason.** A
+ *    JavaScript action, an undecidable `if:`, a `${{ }}` that will not
+ *    resolve, a step that exits non-zero — each fails the execution and says
+ *    what it hit, and the consumers of that job's outputs stay unresolved.
+ *    Guessing is the one move this module never makes.
+ *
+ * `actions/checkout` is the deliberate exception to rule 2. It is provided by
+ * the runner, not run from its repo, and its whole postcondition — the
+ * workspace tree at the commit under test — is something the executor has
+ * already satisfied by materializing the tree. A bare checkout is therefore
+ * recorded as done; a checkout *with inputs* is not modelled and stops.
+ */
+import { spawn } from "node:child_process";
+import { mkdir, mkdtemp, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { evaluate, evaluateValue, UNKNOWN } from "./expr.js";
+/** `owner/repo:job1,job2` as the CLI spells a grant. */
+export function parseGrant(spec) {
+    const colon = spec.indexOf(":");
+    if (colon <= 0)
+        return null;
+    const repo = spec.slice(0, colon);
+    const parts = repo.split("/");
+    if (parts.length !== 2 || parts.some((p) => p === ""))
+        return null;
+    const jobs = spec
+        .slice(colon + 1)
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "");
+    if (jobs.length === 0)
+        return null;
+    return { repo, jobs };
+}
+const err = (reason) => ({ ok: false, reason });
+const SHA_RE = /^[0-9a-f]{40}$/i;
+/**
+ * Render every `${{ }}` in a template to its literal text, or null when any
+ * of them cannot be settled. Null rather than a partial render: a script with
+ * a hole in it is a different program, and running a different program is the
+ * exact lie rule 2 exists to prevent.
+ */
+function renderTemplate(text, scope) {
+    let failed = false;
+    const out = text.replace(/\$\{\{(.*?)\}\}/g, (_whole, inner) => {
+        const val = evaluateValue(String(inner), scope);
+        if (val.kind !== "value") {
+            failed = true;
+            return "";
+        }
+        return String(val.v);
+    });
+    return failed ? null : out;
+}
+/** An `env:` block rendered to concrete strings, every key or nothing. */
+function renderEnvLayer(layer, scope) {
+    if (layer == null)
+        return { ok: true, v: {} };
+    if (typeof layer !== "object" || Array.isArray(layer))
+        return err("env block is not a map");
+    const out = {};
+    for (const [k, raw] of Object.entries(layer)) {
+        const rendered = renderTemplate(String(raw ?? ""), scope);
+        if (rendered == null)
+            return err(`cannot resolve env '${k}'`);
+        out[k] = rendered;
+    }
+    return { ok: true, v: out };
+}
+/**
+ * The `$GITHUB_OUTPUT` file format: `name=value` lines, or a
+ * `name<<DELIMITER … DELIMITER` heredoc for multi-line values. Anything else
+ * fails the parse — the runner fails the step on a malformed line, so
+ * tolerating one here would invent outputs a real run never had.
+ */
+export function parseGithubOutput(text) {
+    const out = {};
+    const lines = text.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        i++;
+        if (line === "")
+            continue;
+        const heredoc = /^([^=<]+)<<(.+)$/.exec(line);
+        if (heredoc != null) {
+            const [, name, delim] = heredoc;
+            const buf = [];
+            for (;;) {
+                if (i >= lines.length)
+                    return null; // unterminated heredoc
+                if (lines[i] === delim) {
+                    i++;
+                    break;
+                }
+                buf.push(lines[i]);
+                i++;
+            }
+            out[name] = buf.join("\n");
+            continue;
+        }
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            return null;
+        out[line.slice(0, eq)] = line.slice(eq + 1);
+    }
+    return out;
+}
+// ------------------------------------------------------------------- actions
+/**
+ * A step-level `uses:` naming another repo: `owner/repo[/path]@ref`. Unlike a
+ * reusable-workflow reference the path may be empty — an action commonly
+ * lives at the repo root. Expressions and `docker://` images return null.
+ */
+function parseActionUses(uses) {
+    if (uses.includes("${{") || uses.startsWith("docker://"))
+        return null;
+    const at = uses.lastIndexOf("@");
+    if (at <= 0)
+        return null;
+    const ref = uses.slice(at + 1);
+    if (ref === "")
+        return null;
+    const [owner, repo, ...rest] = uses.slice(0, at).split("/");
+    if (!owner || !repo)
+        return null;
+    return { path: rest.join("/"), source: { owner, repo, ref } };
+}
+/** Read `action.yml` (or `.yaml`) from a directory, or null if neither exists. */
+async function readActionManifest(dir) {
+    for (const name of ["action.yml", "action.yaml"]) {
+        try {
+            return await readFile(join(dir, name), "utf8");
+        }
+        catch {
+            // fall through to the next spelling
+        }
+    }
+    return null;
+}
+/**
+ * What `inputs.*` means inside a composite action: the caller's `with:`
+ * values over the action's declared defaults, everything a string — action
+ * inputs are untyped, and an input nobody set is the empty string, not a
+ * hole. A value whose `${{ }}` cannot be rendered stays unknown rather than
+ * failing here: it only matters if a step actually reads it, and the read is
+ * where that failure is honest.
+ */
+function bindActionInputs(action, withBlock, scope) {
+    const bind = (raw) => {
+        if (raw == null)
+            return { kind: "value", v: "" };
+        if (typeof raw === "boolean" || typeof raw === "number") {
+            return { kind: "value", v: String(raw) };
+        }
+        const rendered = renderTemplate(String(raw), scope);
+        return rendered == null ? UNKNOWN : { kind: "value", v: rendered };
+    };
+    const out = {};
+    for (const [name, decl] of Object.entries(action?.inputs ?? {})) {
+        out[name] =
+            decl != null && typeof decl === "object" && "default" in decl
+                ? bind(decl["default"])
+                : { kind: "value", v: "" };
+    }
+    if (withBlock != null && typeof withBlock === "object") {
+        for (const [name, raw] of Object.entries(withBlock)) {
+            out[name] = bind(raw);
+        }
+    }
+    return out;
+}
+// ----------------------------------------------------------------- step walk
+/**
+ * A cycle guard, not a fidelity claim: a composite action that includes
+ * itself would otherwise recurse forever. No granted job in practice nests
+ * past one level.
+ */
+const MAX_ACTION_DEPTH = 4;
+const CHECKOUT_RE = /^actions\/checkout@/;
+/**
+ * Walk steps in order, growing the `steps` context as each one completes.
+ * Returns the finished context, or the reason the walk stopped.
+ */
+async function runSteps(steps, scope, ctx) {
+    const stepsCtx = {};
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i] ?? {};
+        const label = `step '${step.id ?? step.name ?? `#${i + 1}`}'`;
+        const stepScope = { ...scope, steps: stepsCtx };
+        if (step.if != null) {
+            const verdict = evaluate(String(step.if), stepScope);
+            if (verdict == null)
+                return err(`cannot decide if: for ${label}`);
+            if (!verdict) {
+                // A skipped step still occupies its id, with no outputs — that is the
+                // empty string every later read gets, and what `||` coalesces past.
+                if (typeof step.id === "string")
+                    stepsCtx[step.id] = { outputs: {} };
+                continue;
+            }
+        }
+        let res;
+        if (typeof step.uses === "string") {
+            res = await runUses(step, label, stepScope, ctx);
+        }
+        else if (step.run != null) {
+            res = await runRun(step, label, stepScope, ctx);
+        }
+        else {
+            return err(`${label} has neither uses nor run`);
+        }
+        if (!res.ok)
+            return res;
+        if (typeof step.id === "string")
+            stepsCtx[step.id] = { outputs: res.v };
+    }
+    return { ok: true, v: stepsCtx };
+}
+/** A `uses:` step: checkout's postcondition, or a composite action, or a stop. */
+async function runUses(step, label, scope, ctx) {
+    const uses = step.uses;
+    if (CHECKOUT_RE.test(uses)) {
+        // Runner-provided, and its postcondition — the head tree at the workspace
+        // path — is already true. But only the bare form: `ref:`, `path:`,
+        // `repository:` each make it a different tree than the one provided.
+        if (step.with != null && Object.keys(step.with).length > 0) {
+            return err(`${label}: actions/checkout with inputs is not modelled`);
+        }
+        return { ok: true, v: {} };
+    }
+    if (ctx.depth + 1 > MAX_ACTION_DEPTH) {
+        return err(`${label}: actions nested deeper than ${MAX_ACTION_DEPTH} levels`);
+    }
+    let actionDir;
+    if (uses.startsWith("./")) {
+        // Relative to the workspace, hermetic-style: the tree under test carries
+        // the action. GitHub resolves it the same way.
+        actionDir = join(ctx.tree, uses.slice(2));
+    }
+    else {
+        const target = parseActionUses(uses);
+        if (target == null)
+            return err(`${label}: unresolvable uses: ${uses}`);
+        const { ref } = target.source;
+        const sha = SHA_RE.test(ref) ? ref : await ctx.deps.resolveRef(target.source);
+        if (sha == null)
+            return err(`${label}: cannot resolve ref for ${uses}`);
+        const source = { ...target.source, sha };
+        const root = await ctx.deps.provideTree(source);
+        if (root == null) {
+            return err(`${label}: cannot materialize ${source.owner}/${source.repo}@${sha}`);
+        }
+        actionDir = target.path === "" ? root : join(root, target.path);
+    }
+    const manifest = await readActionManifest(actionDir);
+    if (manifest == null)
+        return err(`${label}: no action.yml under ${uses}`);
+    let action;
+    try {
+        action = parseYaml(manifest);
+    }
+    catch (e) {
+        return err(`${label}: YAML parse error in ${uses}: ${e}`);
+    }
+    const using = action?.runs?.using;
+    if (using !== "composite") {
+        // A JavaScript or Docker action is a program with its own runtime and its
+        // own view of the world. Running one is a much larger promise than
+        // running a shell step, and no granted job needs it.
+        return err(`${label}: action ${uses} runs via '${using}'; only composite actions are executed`);
+    }
+    const childScope = {
+        inputs: bindActionInputs(action, step.with, scope),
+        github: scope.github,
+    };
+    const walked = await runSteps(action?.runs?.steps ?? [], childScope, {
+        ...ctx,
+        actionPath: actionDir,
+        depth: ctx.depth + 1,
+    });
+    if (!walked.ok)
+        return err(`${label} (${uses}): ${walked.reason}`);
+    // The action's declared outputs are its whole surface: each `value:` is
+    // evaluated against the child's own steps, and every one must land.
+    const outScope = { ...childScope, steps: walked.v };
+    const outputs = {};
+    for (const [name, decl] of Object.entries(action.outputs ?? {})) {
+        const raw = decl?.["value"];
+        if (raw == null)
+            return err(`${label}: output '${name}' of ${uses} has no value`);
+        const rendered = renderTemplate(String(raw), outScope);
+        if (rendered == null)
+            return err(`${label}: cannot resolve output '${name}' of ${uses}`);
+        outputs[name] = rendered;
+    }
+    return { ok: true, v: outputs };
+}
+/** A `run:` step, executed under its declared shell with its declared env. */
+async function runRun(step, label, scope, ctx) {
+    const shell = step.shell == null ? "bash" : String(step.shell);
+    if (shell !== "bash" && shell !== "sh") {
+        return err(`${label}: shell '${shell}' is not modelled`);
+    }
+    const script = renderTemplate(String(step.run), scope);
+    if (script == null)
+        return err(`${label}: cannot resolve \${{ }} in run`);
+    const env = {
+        // The two the runner always provides and scripts assume. Everything else
+        // a step sees, it declared.
+        PATH: process.env.PATH ?? "",
+        HOME: process.env.HOME ?? "",
+        GITHUB_WORKSPACE: ctx.tree,
+    };
+    if (ctx.actionPath != null)
+        env.GITHUB_ACTION_PATH = ctx.actionPath;
+    for (const layer of [...ctx.envLayers, step.env]) {
+        const rendered = renderEnvLayer(layer, scope);
+        if (!rendered.ok)
+            return err(`${label}: ${rendered.reason}`);
+        Object.assign(env, rendered.v);
+    }
+    let cwd = ctx.tree;
+    if (step["working-directory"] != null) {
+        const wd = renderTemplate(String(step["working-directory"]), scope);
+        if (wd == null)
+            return err(`${label}: cannot resolve working-directory`);
+        cwd = resolve(ctx.tree, wd);
+    }
+    const outDir = await mkdtemp(join(tmpdir(), "willfire-out-"));
+    const outFile = join(outDir, "output");
+    await writeFile(outFile, "");
+    // After the layers, so no `env:` block can redirect where outputs land.
+    env.GITHUB_OUTPUT = outFile;
+    const r = await ctx.deps.runCommand({ script, shell, cwd, env });
+    if (r.code !== 0) {
+        const trimmed = r.stderr.trim();
+        const tail = trimmed.slice(trimmed.lastIndexOf("\n") + 1);
+        return err(`${label}: exited ${r.code}${tail === "" ? "" : ` (${tail})`}`);
+    }
+    const outputs = parseGithubOutput(await readFile(outFile, "utf8"));
+    if (outputs == null)
+        return err(`${label}: malformed GITHUB_OUTPUT`);
+    return { ok: true, v: outputs };
+}
+// ------------------------------------------------------------------ executor
+export function makeExecutor(opts) {
+    const { grants, workspace, deps } = opts;
+    const github = {
+        event_name: "pull_request",
+        // Fixed for the run being predicted, and the fact the fleet's
+        // hermetic-vs-published guards branch on.
+        repository: `${workspace.owner}/${workspace.repo}`,
+    };
+    const fail = (reason) => ({ ok: false, reason });
+    return {
+        granted: (source, jobId) => grants.some((g) => g.repo === `${source.owner}/${source.repo}` && g.jobs.includes(jobId)),
+        async executeJob(jobId, job, wf, scope) {
+            // The shapes execution does not model, refused by name rather than run
+            // wrong: a matrix'd job is several executions, and a container changes
+            // what every step means.
+            if (job.strategy != null)
+                return fail(`job '${jobId}' has a strategy; not modelled`);
+            if (job.container != null || job.services != null) {
+                return fail(`job '${jobId}' uses a container or services; not modelled`);
+            }
+            if (!Array.isArray(job.steps))
+                return fail(`job '${jobId}' has no steps`);
+            const tree = await deps.provideTree(workspace);
+            if (tree == null) {
+                return fail(`cannot materialize workspace ${workspace.owner}/${workspace.repo}@${workspace.sha}`);
+            }
+            const jobScope = { ...scope, github: { ...github, ...scope.github } };
+            const walked = await runSteps(job.steps, jobScope, {
+                tree,
+                envLayers: [wf?.env, job.env],
+                deps,
+                depth: 0,
+            });
+            if (!walked.ok)
+                return fail(walked.reason);
+            // The job's `outputs:` map is the whole point of having run anything.
+            // Every declared entry must land; a hole here would hand consumers a
+            // partial map, which the Scope contract calls a lie.
+            const outScope = { ...jobScope, steps: walked.v };
+            const outputs = {};
+            for (const [name, raw] of Object.entries(job.outputs ?? {})) {
+                const rendered = renderTemplate(String(raw), outScope);
+                if (rendered == null)
+                    return fail(`cannot resolve job output '${name}'`);
+                outputs[name] = rendered;
+            }
+            return { ok: true, outputs };
+        },
+    };
+}
+// ------------------------------------------------------------ real-world deps
+/**
+ * The runner's default shell invocations, faithfully: `bash --noprofile
+ * --norc -e -o pipefail` and `sh -e`. Nothing of the parent environment
+ * leaks in beyond what the spec names.
+ */
+export const runShell = (spec) => new Promise((resolvePromise) => {
+    const argv = spec.shell === "bash"
+        ? ["--noprofile", "--norc", "-e", "-o", "pipefail", "-c", spec.script]
+        : ["-e", "-c", spec.script];
+    const child = spawn(spec.shell, argv, {
+        cwd: spec.cwd,
+        env: spec.env,
+        stdio: ["ignore", "ignore", "pipe"],
+    });
+    let stderr = "";
+    child.stderr.on("data", (d) => {
+        stderr += String(d);
+        // Keep the tail; a failure reason wants the last line, not a transcript.
+        if (stderr.length > 4096)
+            stderr = stderr.slice(-4096);
+    });
+    child.on("error", () => resolvePromise({ code: 127, stderr }));
+    child.on("close", (code) => resolvePromise({ code: code ?? 1, stderr }));
+});
+/**
+ * Materialize repo trees from tarballs, one download per commit however many
+ * steps ask. GitHub's tarballs wrap the tree in a single
+ * `owner-repo-shortsha/` directory, which is unwrapped so callers get the
+ * tree root itself. Extraction shells out to `tar` through the same
+ * `RunCommand` seam every other subprocess uses.
+ */
+export function makeTreeProvider(download, runCommand) {
+    const cache = new Map();
+    return (source) => {
+        const key = `${source.owner}/${source.repo}@${source.sha}`;
+        const hit = cache.get(key);
+        if (hit !== undefined)
+            return hit;
+        const p = materialize(source, download, runCommand);
+        cache.set(key, p);
+        return p;
+    };
+}
+async function materialize(source, download, runCommand) {
+    const bytes = await download(source);
+    if (bytes == null)
+        return null;
+    const dir = await mkdtemp(join(tmpdir(), "willfire-tree-"));
+    const archive = join(dir, "tree.tar.gz");
+    await writeFile(archive, bytes);
+    const dest = join(dir, "tree");
+    await mkdir(dest);
+    const r = await runCommand({
+        script: 'tar -xzf "$WILLFIRE_ARCHIVE" -C "$WILLFIRE_DEST"',
+        shell: "bash",
+        cwd: dir,
+        env: {
+            PATH: process.env.PATH ?? "",
+            WILLFIRE_ARCHIVE: archive,
+            WILLFIRE_DEST: dest,
+        },
+    });
+    if (r.code !== 0)
+        return null;
+    const entries = await readdir(dest);
+    if (entries.length === 1) {
+        const sub = join(dest, entries[0]);
+        if ((await stat(sub)).isDirectory())
+            return sub;
+    }
+    return dest;
+}

package/dist/expr.d.ts

@@ -40,6 +40,16 @@
 export type Val = {
     kind: "value";
     v: string | number | boolean;
+}
+/**
+ * An array or an object, which only `fromJSON` produces. Kept apart from
+ * `value` because nothing else in the language accepts one: comparison
+ * refuses it, and its truthiness is not modelled. Matrix expansion is the
+ * one consumer, and it asks for the array directly.
+ */
+ | {
+    kind: "json";
+    v: unknown[] | Record<string, unknown>;
 } | {
     kind: "truthy";
 } | {
@@ -58,12 +68,50 @@ export interface Scope {
     inputs?: Record<string, Val>;
     /** `github.*` values that are fixed for the run being predicted. */
     github?: Record<string, string>;
+    /**
+     * Outputs of jobs this workflow's jobs `needs`, keyed by job id.
+     *
+     * `outputs` is the *complete* set for that job, which is what makes a key
+     * that is absent from it mean the empty string — the same answer the runner
+     * gives for an output no step wrote. Handing in a partial map is therefore a
+     * lie, not a shortcut: leave the job out entirely instead, and every lookup
+     * against it stays unknown.
+     *
+     * The values are raw strings, because that is what a step wrote to
+     * `$GITHUB_OUTPUT` and what the runner substitutes. Parsing eagerly would
+     * break the guards written against them — `!= '[]'` compares a string to a
+     * string, and an array on the left makes it unknown. `fromJSON` is the only
+     * thing that turns one into a structure, at the point the workflow asks.
+     */
+    needs?: Record<string, {
+        outputs: Record<string, string>;
+    }>;
+    /**
+     * Outputs of steps that already ran, keyed by step id. Only one caller can
+     * fill this honestly: the executor's step walk (see execute.ts), which is
+     * the single place a step has actually run by the time an expression reads
+     * it. The contract is the same as `needs`: a step named here carries its
+     * *complete* output set, so an absent key is the empty string the runner
+     * substitutes, while a step this map does not name stays unknown. A skipped
+     * step is present with no outputs at all — which is exactly what lets
+     * `steps.a.outputs.x || steps.b.outputs.x` coalesce past it.
+     */
+    steps?: Record<string, {
+        outputs: Record<string, string>;
+    }>;
 }
 /**
- * Evaluate a condition to a truthiness, or null when it cannot be settled.
+ * Evaluate an expression to a value, or UNKNOWN when it cannot be settled.
  *
- * The `${{ }}` wrapper is optional in `if:` and stripped when present. A
- * condition that is only *partly* wrapped (`foo ${{ bar }} baz`) is a string
+ * The `${{ }}` wrapper is optional in `if:` and stripped when present. An
+ * expression that is only *partly* wrapped (`foo ${{ bar }} baz`) is a string
  * interpolation rather than an expression, and is not modelled.
+ *
+ * A `if:` wants {@link evaluate}, which is this narrowed to truthiness. This
+ * one is for the places that need the value itself — a matrix axis written as
+ * `${{ fromJSON(...) }}` is an array, and its truthiness says nothing about
+ * how many jobs it schedules.
  */
+export declare function evaluateValue(expr: string, scope?: Scope): Val;
+/** Evaluate a condition to a truthiness, or null when it cannot be settled. */
 export declare function evaluate(cond: string, scope?: Scope): boolean | null;

package/dist/expr.js

@@ -43,6 +43,10 @@ function truthy(val) {
             return false;
         case "unknown":
             return null;
+        // GitHub does cast an array or an object to a boolean, but no workflow
+        // asks it to, and the answer is not worth guessing at to find out.
+        case "json":
+            return null;
         case "value": {
             const v = val.v;
             if (typeof v === "boolean")
@@ -264,10 +268,36 @@ class Parser {
             const v = this.scope.github?.[rest];
             return v === undefined ? UNKNOWN : { kind: "value", v };
         }
-        // `needs.*`, `steps.*`, `matrix.*`, `env.*`, `vars.*`, `secrets.*`: all
-        // require something that has not happened yet at prediction time. This is
-        // the seam where a `needs` context would attach if willfire ever computes
-        // a called workflow's outputs ahead of the run.
+        if (head === "needs") {
+            // Only `needs.<job>.outputs.<name>` is modelled. `needs.<job>.result`
+            // is a verdict on a run that has not happened; anything else is not a
+            // shape the context has.
+            const parts = rest.split(".");
+            if (parts.length !== 3 || parts[1] !== "outputs")
+                return UNKNOWN;
+            const job = this.scope.needs?.[parts[0]];
+            if (job == null)
+                return UNKNOWN;
+            // A known job's missing output is the empty string, not a hole: the
+            // caller promised the set is complete, and that is what the runner
+            // substitutes for an output no step wrote.
+            return { kind: "value", v: job.outputs[parts[2]] ?? "" };
+        }
+        if (head === "steps") {
+            // The same shape as `needs`, for the same reason: only
+            // `steps.<id>.outputs.<name>` is modelled. `steps.<id>.outcome` and
+            // `.conclusion` are verdicts on how a step ran, which the executor does
+            // not track — a failed step fails the whole execution instead.
+            const parts = rest.split(".");
+            if (parts.length !== 3 || parts[1] !== "outputs")
+                return UNKNOWN;
+            const step = this.scope.steps?.[parts[0]];
+            if (step == null)
+                return UNKNOWN;
+            return { kind: "value", v: step.outputs[parts[2]] ?? "" };
+        }
+        // `matrix.*`, `env.*`, `vars.*`, `secrets.*`: all require something that
+        // has not happened yet at prediction time.
         return UNKNOWN;
     }
 }
@@ -332,17 +362,45 @@ function compare(op, left, right) {
         return asBool(a > b);
     return asBool(a >= b);
 }
+/**
+ * `fromJSON(s)` on a known string.
+ *
+ * The result is sorted into the lattice rather than dropped in whole: a scalar
+ * is an ordinary value and stays comparable, `null` has a known truthiness and
+ * no useful value, and only an array or an object needs the `json` point.
+ * Anything unparseable is unknown — a workflow that reaches this at runtime
+ * fails, and predicting a failure is not this function's job.
+ */
+function fromJson(arg) {
+    if (arg.kind !== "value" || typeof arg.v !== "string")
+        return UNKNOWN;
+    let parsed;
+    try {
+        parsed = JSON.parse(arg.v);
+    }
+    catch {
+        return UNKNOWN;
+    }
+    if (parsed === null)
+        return { kind: "falsy" };
+    if (typeof parsed === "object")
+        return { kind: "json", v: parsed };
+    return { kind: "value", v: parsed };
+}
 /**
  * The functions worth modelling.
  *
  * `always()` is true by definition. `contains` on two known strings is the one
- * that unlocks the fleet's `gates` pattern. `success()`, `failure()` and
- * `cancelled()` depend on jobs that have not run, and everything else is
- * simply not modelled — all unknown.
+ * that unlocks the fleet's `gates` pattern. `fromJSON` is what a dynamic matrix
+ * axis is built out of. `success()`, `failure()` and `cancelled()` depend on
+ * jobs that have not run, and everything else is simply not modelled — all
+ * unknown.
  */
 function applyFunction(name, args) {
     if (name === "always")
         return { kind: "value", v: true };
+    if (name === "fromjson" && args.length === 1)
+        return fromJson(args[0]);
     if (name === "contains" && args.length === 2) {
         const [hay, needle] = args;
         if (hay.kind !== "value" || needle.kind !== "value")
@@ -363,26 +421,35 @@ function applyFunction(name, args) {
 }
 // ---------------------------------------------------------------------- entry
 /**
- * Evaluate a condition to a truthiness, or null when it cannot be settled.
+ * Evaluate an expression to a value, or UNKNOWN when it cannot be settled.
  *
- * The `${{ }}` wrapper is optional in `if:` and stripped when present. A
- * condition that is only *partly* wrapped (`foo ${{ bar }} baz`) is a string
+ * The `${{ }}` wrapper is optional in `if:` and stripped when present. An
+ * expression that is only *partly* wrapped (`foo ${{ bar }} baz`) is a string
  * interpolation rather than an expression, and is not modelled.
+ *
+ * A `if:` wants {@link evaluate}, which is this narrowed to truthiness. This
+ * one is for the places that need the value itself — a matrix axis written as
+ * `${{ fromJSON(...) }}` is an array, and its truthiness says nothing about
+ * how many jobs it schedules.
  */
-export function evaluate(cond, scope = {}) {
-    const stripped = cond.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
+export function evaluateValue(expr, scope = {}) {
+    const stripped = expr.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
     if (stripped === "")
-        return null;
+        return UNKNOWN;
     if (stripped.includes("${{"))
-        return null;
+        return UNKNOWN;
     const toks = tokenize(stripped);
     if (toks == null || toks.length === 0)
-        return null;
+        return UNKNOWN;
     const p = new Parser(toks, scope);
     const val = p.or();
-    // Trailing tokens mean the grammar did not cover this condition; whatever
+    // Trailing tokens mean the grammar did not cover this expression; whatever
     // was parsed describes only a prefix of it, so it decides nothing.
     if (!p.done())
-        return null;
-    return truthy(val);
+        return UNKNOWN;
+    return val;
+}
+/** Evaluate a condition to a truthiness, or null when it cannot be settled. */
+export function evaluate(cond, scope = {}) {
+    return truthy(evaluateValue(cond, scope));
 }

package/dist/predict.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Octokit } from "@octokit/rest";
+import { type ExecutionGrant, type JobExecutor } from "./execute.js";
 import { type Scope } from "./expr.js";
 interface EntryBase {
     workflow: string;
@@ -111,6 +112,17 @@ export interface PredictOptions {
      * to a workflow narrowing `types:`, where it matters completely.
      */
     action?: PrEventAction;
+    /**
+     * Jobs willfire may *execute* to resolve what reading cannot — the fleet's
+     * `detect` job, whose outputs feed every dynamic matrix downstream of it.
+     *
+     * Off by default, and mechanism only: willfire has no opinion about which
+     * jobs are safe to run. The caller that knows names them, one repo and job
+     * id at a time (see {@link ExecutionGrant}), and an execution that fails
+     * for any reason leaves the dependent entries exactly as unresolved as
+     * they were — with the failure spelled into their reasons.
+     */
+    execute?: ExecutionGrant[];
 }
 export interface Ctx {
     action: string;
@@ -120,13 +132,14 @@ export interface Ctx {
 type Workflow = Record<string, any>;
 type Combo = Record<string, any> | null;
 /** Return list of matrix combination dicts, or null if dynamic. */
-export declare function expandMatrix(strategy: any): Combo[] | null;
+export declare function expandMatrix(strategy: any, scope?: Scope): Combo[] | null;
 /**
  * Return run|skipped|unknown for a job-level `if:`.
  *
- * `scope` carries the inputs the calling workflow passed down. Without it a
- * reusable workflow's guards are all unknown, because every one of them is
- * written against `inputs.*`.
+ * `scope` carries the inputs the calling workflow passed down, and any job
+ * outputs the caller knows. Without it a reusable workflow's guards are all
+ * unknown, because every one of them is written against `inputs.*` or
+ * `needs.*`.
  */
 export declare function evalIf(cond: any, scope?: Scope): "run" | "skipped" | "unknown";
 /**
@@ -217,8 +230,13 @@ export declare function parseUses(uses: string): UsesTarget | null;
  * Expand one already-parsed workflow into its job entries. Exported so check
  * names can be tested against recorded GitHub behaviour without a network
  * round-trip; `predict` is the API you want.
+ *
+ * `scope` seeds what this workflow's own `${{ }}` resolve against — notably
+ * `needs`, the outputs of jobs that have not run. Nothing here works out what
+ * those are; a caller that knows hands them in, and a caller that does not
+ * leaves them out and gets `unknown` where they would have been used.
  */
-export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, reader: WorkflowReader, source: WorkflowSource): Promise<ExpandedJob[]>;
+export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, reader: WorkflowReader, source: WorkflowSource, scope?: Scope, executor?: JobExecutor): Promise<ExpandedJob[]>;
 export declare function makeOctokit(): Octokit;
 export declare function predict(octokit: Octokit, repo: string, prNumber: number, opts?: PredictOptions): Promise<Prediction>;
 export {};

package/dist/predict.js

@@ -12,7 +12,8 @@
 // src/names.test.ts.
 import { Octokit } from "@octokit/rest";
 import { parse as parseYaml } from "yaml";
-import { evaluate, UNKNOWN } from "./expr.js";
+import { makeExecutor, makeTreeProvider, parseGrant, runShell, } from "./execute.js";
+import { evaluate, evaluateValue, UNKNOWN } from "./expr.js";
 /** Tag a job display name. Rejects the workflow-level sentinel. */
 export const jobName = (name) => name;
 /** Narrow to the workflow-level variant without inspecting the sentinel. */
@@ -126,12 +127,34 @@ function workflowDispatches(wf, ctx) {
     }
     return [true, "trigger matched"];
 }
-function expandMatrixDetailed(strategy) {
+/**
+ * The values of one matrix axis, or null when they cannot be known.
+ *
+ * A plain list is itself. An axis written as an expression —
+ * `language: ${{ fromJSON(needs.detect.outputs.coverage_languages) }}` — is
+ * the values another job computed, and is knowable exactly when the scope
+ * carries that job's outputs. Anything else stays null, which is what makes
+ * the whole job `unknown` rather than a guess at how many checks it creates.
+ */
+function axisValues(v, scope) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v !== "string")
+        return null;
+    const val = evaluateValue(v, scope);
+    if (val.kind !== "json" || !Array.isArray(val.v))
+        return null;
+    return val.v;
+}
+function expandMatrixDetailed(strategy, scope = {}) {
     const matrix = strategy?.matrix;
     if (matrix == null)
         return [null];
+    // `matrix: ${{ ... }}` — the whole matrix as one expression, rather than the
+    // per-axis form below. It yields include-style entries, not axes, so it is a
+    // separate expansion and is not modelled.
     if (typeof matrix === "string")
-        return null; // ${{ fromJSON(...) }}
+        return null;
     const include = matrix.include ?? [];
     const exclude = matrix.exclude ?? [];
     if (typeof include === "string" || typeof exclude === "string")
@@ -140,9 +163,10 @@ function expandMatrixDetailed(strategy) {
     for (const [k, v] of Object.entries(matrix)) {
         if (k === "include" || k === "exclude")
             continue;
-        if (!Array.isArray(v))
+        const vals = axisValues(v, scope);
+        if (vals == null)
             return null;
-        axes[k] = v;
+        axes[k] = vals;
     }
     const axisKeys = Object.keys(axes);
     let combos = [{ values: {}, displayKeys: axisKeys }];
@@ -177,8 +201,8 @@ function expandMatrixDetailed(strategy) {
     return combos;
 }
 /** Return list of matrix combination dicts, or null if dynamic. */
-export function expandMatrix(strategy) {
-    const detailed = expandMatrixDetailed(strategy);
+export function expandMatrix(strategy, scope = {}) {
+    const detailed = expandMatrixDetailed(strategy, scope);
     return detailed == null ? null : detailed.map((c) => (c == null ? null : c.values));
 }
 /**
@@ -283,20 +307,30 @@ function skippedDisplayName(jobId, job) {
  * resolve instead of hanging the job on an unknown.
  */
 const PR_GITHUB_CONTEXT = { event_name: "pull_request" };
+/**
+ * A scope with the fixed pull-request facts filled in.
+ *
+ * Every `${{ }}` this module evaluates — a job `if:`, a matrix axis — is
+ * evaluated for the same event, so they all get the same `github.*`. Anything
+ * the caller states wins; there is nothing here worth overriding, but a scope
+ * that silently ignored what it was handed would be the wrong shape.
+ */
+const prScope = (scope) => ({
+    ...scope,
+    github: { ...PR_GITHUB_CONTEXT, ...scope.github },
+});
 /**
  * Return run|skipped|unknown for a job-level `if:`.
  *
- * `scope` carries the inputs the calling workflow passed down. Without it a
- * reusable workflow's guards are all unknown, because every one of them is
- * written against `inputs.*`.
+ * `scope` carries the inputs the calling workflow passed down, and any job
+ * outputs the caller knows. Without it a reusable workflow's guards are all
+ * unknown, because every one of them is written against `inputs.*` or
+ * `needs.*`.
  */
 export function evalIf(cond, scope = {}) {
     if (cond == null)
         return "run";
-    const verdict = evaluate(String(cond), {
-        inputs: scope.inputs,
-        github: { ...PR_GITHUB_CONTEXT, ...scope.github },
-    });
+    const verdict = evaluate(String(cond), prScope(scope));
     if (verdict === null)
         return "unknown";
     return verdict ? "run" : "skipped";
@@ -400,13 +434,43 @@ export function parseUses(uses) {
         return null;
     return { path, source: { owner, repo, ref } };
 }
-async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefixResolved = true, scope = {}) {
+async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefixResolved = true, scope = {}, executor) {
     const entries = [];
     const jobs = wf.jobs ?? {};
     const statuses = {};
+    // Execute what the caller granted, before anything reads `needs`. The
+    // grant names the repo the workflow *file* lives in, so a granted callee
+    // job fires here in the recursion, where `source` is that repo. The guard
+    // is the same `evalIf` the main loop applies — same scope, same verdict —
+    // so a job is executed exactly when it is predicted to run. A job that
+    // would not run is not executed; a job that fails to execute contributes
+    // nothing but its reason, which `execNote` threads into the entries that
+    // needed it.
+    let scoped = scope;
+    const execFailures = {};
+    if (executor != null) {
+        for (const [jobId, jobRaw] of Object.entries(jobs)) {
+            if (!executor.granted(source, jobId))
+                continue;
+            const job = jobRaw ?? {};
+            if (evalIf(job.if, scoped) !== "run")
+                continue;
+            const res = await executor.executeJob(jobId, job, wf, scoped);
+            if (res.ok) {
+                scoped = { ...scoped, needs: { ...scoped.needs, [jobId]: { outputs: res.outputs } } };
+            }
+            else {
+                execFailures[jobId] = res.reason;
+            }
+        }
+    }
+    const execNote = (needs) => {
+        const failed = needs.find((n) => n in execFailures);
+        return failed == null ? "" : `; executing '${failed}' failed: ${execFailures[failed]}`;
+    };
     for (const [jobId, jobRaw] of Object.entries(jobs)) {
         const job = jobRaw ?? {};
-        let status = evalIf(job.if, scope);
+        let status = evalIf(job.if, scoped);
         let reason = job.if != null ? `if: ${JSON.stringify(job.if)}` : "";
         let needs = job.needs ?? [];
         if (typeof needs === "string")
@@ -438,7 +502,7 @@ async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefi
             });
             continue;
         }
-        const combos = expandMatrixDetailed(job.strategy);
+        const combos = expandMatrixDetailed(job.strategy, prScope(scoped));
         if ("uses" in job) {
             // Reusable workflow call. The calling job produces no check of its own;
             // each called job becomes `<calling job name> / <called job name>`, and
@@ -451,7 +515,7 @@ async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefi
                     job: prefix + jobId,
                     checkName: null,
                     status: "unknown",
-                    reason: "dynamic matrix on reusable workflow call",
+                    reason: "dynamic matrix on reusable workflow call" + execNote(needs),
                 });
                 continue;
             }
@@ -494,7 +558,10 @@ async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefi
                     else {
                         try {
                             subWf = parseYaml(content);
-                            subScope = { inputs: calleeInputs(job.with, subWf ?? {}) };
+                            // `inputs.*` changes at the call boundary; `github.*` does not.
+                            // A callee's jobs run in the caller's repo, so the facts seeded
+                            // at the top of the prediction stay true all the way down.
+                            subScope = { inputs: calleeInputs(job.with, subWf ?? {}), github: scoped.github };
                         }
                         catch (e) {
                             failure = `YAML parse error in ${uses}: ${e}`;
@@ -515,7 +582,7 @@ async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefi
                     });
                     continue;
                 }
-                entries.push(...(await expandJobs(subWf, ctx, reader, subSource, depth + 1, `${baseName} / `, nameResolved, subScope)));
+                entries.push(...(await expandJobs(subWf, ctx, reader, subSource, depth + 1, `${baseName} / `, nameResolved, subScope, executor)));
             }
             continue;
         }
@@ -524,7 +591,7 @@ async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefi
                 job: prefix + jobId,
                 checkName: null,
                 status: "unknown",
-                reason: "dynamic matrix",
+                reason: "dynamic matrix" + execNote(needs),
             });
             continue;
         }
@@ -545,9 +612,14 @@ async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefi
  * Expand one already-parsed workflow into its job entries. Exported so check
  * names can be tested against recorded GitHub behaviour without a network
  * round-trip; `predict` is the API you want.
+ *
+ * `scope` seeds what this workflow's own `${{ }}` resolve against — notably
+ * `needs`, the outputs of jobs that have not run. Nothing here works out what
+ * those are; a caller that knows hands them in, and a caller that does not
+ * leaves them out and gets `unknown` where they would have been used.
  */
-export function expandWorkflowJobs(wf, ctx, reader, source) {
-    return expandJobs(wf, ctx, reader, source);
+export function expandWorkflowJobs(wf, ctx, reader, source, scope = {}, executor) {
+    return expandJobs(wf, ctx, reader, source, 0, "", true, scope, executor);
 }
 // ------------------------------------------------------------------- pipeline
 export function makeOctokit() {
@@ -650,10 +722,47 @@ export async function predict(octokit, repo, prNumber, opts = {}) {
         return content;
     };
     const reader = { fetchWorkflow, resolveRef };
+    // The executor exists only when the caller granted something. Trees come
+    // from the tarball endpoint at the resolved commit, and every subprocess —
+    // `tar` included — goes through the one `runShell` seam.
+    let executor;
+    if (opts.execute != null && opts.execute.length > 0) {
+        const download = async (src) => {
+            try {
+                const { data } = await octokit.rest.repos.downloadTarballArchive({
+                    owner: src.owner,
+                    repo: src.repo,
+                    ref: src.sha,
+                });
+                return new Uint8Array(data);
+            }
+            catch {
+                // Private, deleted, rate limit, network: one answer, and the entries
+                // behind it stay unresolved with the failure named.
+                return null;
+            }
+        };
+        executor = makeExecutor({
+            grants: opts.execute,
+            workspace: headSource,
+            deps: {
+                provideTree: makeTreeProvider(download, runShell),
+                runCommand: runShell,
+                resolveRef,
+            },
+        });
+    }
     const workflows = await octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
         ...base,
         per_page: 100,
     });
+    // `github.repository` is fixed for everything predicted here: reusable
+    // workflows and composite actions all run in the repo the PR is against.
+    // Seeding it once makes guards like the fleet's hermetic-vs-published
+    // `github.repository ==` checks decidable everywhere, granted or not.
+    const prFacts = {
+        github: { repository: `${headSource.owner}/${headSource.repo}` },
+    };
     const entries = [];
     for (const w of workflows) {
         const path = w.path;
@@ -702,7 +811,7 @@ export async function predict(octokit, repo, prNumber, opts = {}) {
             entries.push({ workflow: path, job: "*", status: "no-dispatch", reason });
             continue;
         }
-        for (const j of await expandJobs(wf, ctx, reader, headSource)) {
+        for (const j of await expandJobs(wf, ctx, reader, headSource, 0, "", true, prFacts, executor)) {
             entries.push({
                 workflow: path,
                 job: jobName(j.job),
@@ -729,7 +838,8 @@ function finalizePrediction(entries, skip, sources) {
     };
 }
 // ------------------------------------------------------------------------ CLI
-const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened] [--json]";
+const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened]" +
+    " [--execute owner/repo:job1,job2]... [--json]";
 const isPrEventAction = (v) => v === "opened" || v === "synchronize" || v === "reopened";
 function parseArgs(argv) {
     const get = (flag) => {
@@ -751,13 +861,30 @@ function parseArgs(argv) {
         console.error(USAGE);
         process.exit(2);
     }
-    return { repo, pr: Number(pr), json: argv.includes("--json"), action };
+    // Repeatable, one grant per flag. A malformed grant is refused for the same
+    // reason a bad --action is: silently dropping it would predict without the
+    // execution the caller thought they asked for.
+    const execute = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] !== "--execute")
+            continue;
+        const spec = argv[i + 1];
+        const grant = spec == null ? null : parseGrant(spec);
+        if (grant == null) {
+            console.error(`bad --execute: ${spec}`);
+            console.error(USAGE);
+            process.exit(2);
+        }
+        execute.push(grant);
+    }
+    return { repo, pr: Number(pr), json: argv.includes("--json"), action, execute };
 }
 const isMain = /predict\.(ts|js)$|\/willfire$/.test(process.argv[1] ?? "");
 if (isMain) {
     const args = parseArgs(process.argv.slice(2));
     const prediction = await predict(makeOctokit(), args.repo, args.pr, {
         action: args.action,
+        execute: args.execute,
     });
     const { entries, skip, sources } = prediction;
     if (args.json) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willfire",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
   "packageManager": "pnpm@10.33.0",