laneyard 0.1.0 → 0.2.0

package/dist/src/git/workspace.js

@@ -29,16 +29,33 @@ export class Workspace {
      *
      * An HTTPS URL can carry a password — `https://user:token@github.com/…`
      * is perfectly legal in `config.yml`. But git errors end up in the run's
-     * log file. General secret redaction comes at the next milestone; this
-     * particular leak comes from our own formatting, and is fixed here.
+     * log file. The vault's redaction does not help here: the repository URL is
+     * configuration, not a stored secret, so this leak — which comes from our own
+     * formatting — has to be closed on the spot.
      */
     redact(text) {
         return text.split(this.gitUrl).join("<repository>");
     }
-    async git(args, cwd = this.path) {
+    async git(args, cwd = this.path, timeout) {
+        return (await this.gitRaw(args, cwd, timeout)).trim();
+    }
+    /**
+     * Same as `git`, but without trimming the output.
+     *
+     * `status --porcelain` output is column-sensitive: its first two characters
+     * are a status code that can themselves be a literal space. Trimming the
+     * whole blob — fine for a commit hash or a single config value — would eat
+     * that leading space and misalign every line parsed after it.
+     */
+    async gitRaw(args, cwd = this.path, timeout) {
         try {
-            const { stdout } = await exec("git", args, { cwd, env: this.env(), maxBuffer: 32 * 1024 * 1024 });
-            return stdout.trim();
+            const { stdout } = await exec("git", args, {
+                cwd,
+                env: this.env(),
+                maxBuffer: 32 * 1024 * 1024,
+                ...(timeout === undefined ? {} : { timeout }),
+            });
+            return stdout;
         }
         catch (cause) {
             const err = cause;
@@ -46,6 +63,18 @@ export class Workspace {
             throw new Error(`git ${this.redact(args.join(" "))} failed: ${this.redact(detail)}`);
         }
     }
+    /**
+     * Asks the remote for its branches, and nothing else.
+     *
+     * Reads no working copy and writes nothing, so it answers the one question
+     * the readiness checklist asks: would a run reach this repository on its own?
+     * The timeout matters as much as the exit code — with `GIT_TERMINAL_PROMPT=0`
+     * git gives up on a credentials prompt, but a host that never answers would
+     * otherwise hang the checklist exactly the way it hangs a run at 2am.
+     */
+    async probeRemote(timeoutMs = 10_000) {
+        await this.git(["ls-remote", "--heads", this.gitUrl], process.cwd(), timeoutMs);
+    }
     async exists() {
         try {
             await access(join(this.path, ".git"));
@@ -71,6 +100,67 @@ export class Workspace {
     async headSha() {
         return this.git(["rev-parse", "HEAD"]);
     }
+    /**
+     * Paths with uncommitted changes, tracked only — the same rule as
+     * `isDirty`, for the same reason: a build scatters untracked files around,
+     * and listing them here would bury the change someone actually made.
+     */
+    async status() {
+        const raw = await this.gitRaw(["status", "--porcelain", "--untracked-files=no"]);
+        // Porcelain v1: two status letters, a space, then the path. The trailing
+        // split produces one empty element for the final newline; drop it rather
+        // than turn it into a bogus empty path.
+        return raw
+            .split("\n")
+            .filter((line) => line.length > 0)
+            .map((line) => line.slice(3));
+    }
+    /** The unified diff of uncommitted changes, as text. Every path if none is given. */
+    async diff(path) {
+        return this.git(path === undefined ? ["diff"] : ["diff", "--", path]);
+    }
+    /**
+     * Stages exactly the given paths and commits them — never `git add -A`. A
+     * build leaves files scattered in the workspace, and committing them
+     * because they happened to be there is how something ends up in someone's
+     * release.
+     *
+     * Commits under the repository's own git identity if it has one; otherwise
+     * as `Laneyard <laneyard@localhost>`, because a commit from a name nobody
+     * recognises is worse than one that admits what made it. The identity
+     * actually used is returned so the interface can say so.
+     */
+    async commit(message, paths) {
+        if (paths.length === 0)
+            throw new Error("commit: no paths given");
+        await this.git(["add", "--", ...paths]);
+        const identity = await this.gitIdentity();
+        const author = identity ?? "Laneyard <laneyard@localhost>";
+        const asLaneyard = identity
+            ? []
+            : ["-c", "user.name=Laneyard", "-c", "user.email=laneyard@localhost"];
+        await this.git([...asLaneyard, "commit", "-m", message]);
+        return { author };
+    }
+    /**
+     * `name <email>` from the repository's own git configuration — local or
+     * global, however git itself resolves it for this workspace — or null if
+     * none is set at all.
+     */
+    async gitIdentity() {
+        try {
+            const name = await this.git(["config", "user.name"]);
+            const email = await this.git(["config", "user.email"]);
+            return name && email ? `${name} <${email}>` : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Pushes the branch, surfacing git's own message on failure rather than a generic one. */
+    async push(branch) {
+        await this.git(["push", "origin", branch]);
+    }
     /**
      * Guarantees the clone is present, without touching the current branch.
      *

package/dist/src/heuristics/blocking-actions.js

@@ -0,0 +1,45 @@
+export const BLOCKING_RULES = [
+    {
+        action: "prompt",
+        because: "asks a question and waits for an answer",
+        fix: "Remove it from the lane, or give it a default that applies when `CI` is set.",
+    },
+    {
+        action: "match",
+        when: { arg: "readonly", equals: false },
+        because: "may create certificates, which needs an Apple account interactively",
+        fix: "Pass `readonly: true` so it only fetches what already exists.",
+    },
+    {
+        action: "sync_code_signing",
+        when: { arg: "readonly", equals: false },
+        because: "may create certificates, which needs an Apple account interactively",
+        fix: "Pass `readonly: true` so it only fetches what already exists.",
+    },
+    {
+        action: "sigh",
+        because: "renews provisioning profiles, which needs an Apple account interactively",
+        fix: "Use `match` in readonly mode instead, with profiles stored in a repository.",
+    },
+];
+/**
+ * Applies the table to the actions a lane calls.
+ *
+ * A rule whose `when` names an argument the lane didn't pass literally is not
+ * reported: the sidecar already dropped that argument rather than guess at
+ * it (see `ruby/introspect.rb`), so `arg in action.args` is false and the
+ * rule stays silent instead of pretending to know the answer.
+ */
+export function findBlockingActions(actions) {
+    const findings = [];
+    for (const action of actions) {
+        for (const rule of BLOCKING_RULES) {
+            if (rule.action !== action.name)
+                continue;
+            if (rule.when && action.args[rule.when.arg] !== rule.when.equals)
+                continue;
+            findings.push({ action: rule.action, because: rule.because, fix: rule.fix });
+        }
+    }
+    return findings;
+}

package/dist/src/heuristics/readiness.js

@@ -0,0 +1,193 @@
+import { findBlockingActions } from "./blocking-actions.js";
+const ok = (detail) => ({ state: "ok", detail });
+const warn = (detail, fix, fixIn) => ({
+    state: "warn",
+    detail,
+    ...(fix === undefined ? {} : { fix }),
+    ...(fixIn === undefined ? {} : { fixIn }),
+});
+const undetermined = (detail, fix) => ({
+    state: "unknown",
+    detail,
+    ...(fix === undefined ? {} : { fix }),
+});
+/** A rejection is not always an `Error`; a checklist saying "undefined" is worse than useless. */
+const reasonOf = (cause) => cause instanceof Error ? cause.message : String(cause);
+/** Identity and wording live here so a check and its fallback cannot drift apart. */
+const META = {
+    repository: { id: "repository", title: "repository reachable without a password" },
+    dependencies: { id: "dependencies", title: "dependencies installable" },
+    appStoreConnect: { id: "app-store-connect", title: "App Store Connect authentication" },
+    match: { id: "match", title: "match usable without intervention" },
+    blockingActions: { id: "blocking-actions", title: "no action known to stop and ask" },
+};
+/**
+ * Does the remote answer without asking anyone for credentials?
+ *
+ * The probe is injected — `Workspace` already knows how to run git with
+ * `GIT_TERMINAL_PROMPT=0` and how to keep the repository URL, which may carry a
+ * token, out of its own error messages. Redacting is the probe's job, not this
+ * check's: whatever it rejects with is repeated verbatim.
+ */
+export async function checkRepository(probe) {
+    try {
+        await probe();
+        return { ...META.repository, ...ok("the remote answers without asking for credentials.") };
+    }
+    catch (cause) {
+        return {
+            ...META.repository,
+            ...warn(reasonOf(cause), "Give the project a key it can use without a passphrase — " +
+                "`git_auth: {kind: ssh_key, ref: /path/to/key}` in config.yml — or a URL that needs no password. " +
+                "A run that meets a credentials prompt does not fail: it waits."),
+        };
+    }
+}
+export async function checkDependencies(input) {
+    const { workspace } = input;
+    if (!workspace.ok) {
+        return { ...META.dependencies, ...undetermined(`could not read the workspace: ${workspace.reason}`) };
+    }
+    if (workspace.value.hasGemfile) {
+        try {
+            await input.bundleCheck();
+            return { ...META.dependencies, ...ok("the Gemfile's bundle is installed.") };
+        }
+        catch (cause) {
+            return {
+                ...META.dependencies,
+                ...warn(reasonOf(cause), "Run `bundle install` in the project's workspace."),
+            };
+        }
+    }
+    let fastlane;
+    try {
+        fastlane = await input.findFastlane();
+    }
+    catch (cause) {
+        return { ...META.dependencies, ...undetermined(`could not look for fastlane: ${reasonOf(cause)}`) };
+    }
+    if (fastlane !== null) {
+        // Not a failure, but a fact worth stating: a system fastlane can be
+        // upgraded underneath a project that was working yesterday.
+        return {
+            ...META.dependencies,
+            ...ok(`no Gemfile — runs use ${fastlane}, whose version nothing pins.`),
+        };
+    }
+    return {
+        ...META.dependencies,
+        ...warn("no Gemfile, and no fastlane on the PATH: a run has nothing to execute.", 'Add a Gemfile with `gem "fastlane"` and run `bundle install`, or install fastlane system-wide.'),
+    };
+}
+/** Any suffix: the key is split across several variables, and their names vary by lane. */
+const API_KEY = /^APP_STORE_CONNECT_API_KEY/;
+const STORE_API_KEY = "Store an App Store Connect API key — `APP_STORE_CONNECT_API_KEY_ID`, " +
+    "`APP_STORE_CONNECT_API_KEY_ISSUER_ID` and the `.p8` contents — from the secrets tab. " +
+    "An API key does not expire on its own.";
+export function checkAppStoreConnect(secretKeys) {
+    if (secretKeys.some((key) => API_KEY.test(key))) {
+        return { ...META.appStoreConnect, ...ok("an App Store Connect API key is in the vault.") };
+    }
+    if (secretKeys.includes("FASTLANE_SESSION")) {
+        return {
+            ...META.appStoreConnect,
+            ...warn("only a FASTLANE_SESSION: Apple sessions expire, and the run that finds it expired " +
+                "stops and asks for a verification code.", STORE_API_KEY, "secrets"),
+        };
+    }
+    return {
+        ...META.appStoreConnect,
+        ...warn("no App Store Connect credential in the vault: a lane that uploads will ask for an Apple ID.", STORE_API_KEY, "secrets"),
+    };
+}
+/** The two names for the same action. `match` is the older one, still the common one. */
+const MATCH_ACTIONS = new Set(["match", "sync_code_signing"]);
+/** "beta and release" reads better than a list of one, and than a trailing comma. */
+function nameList(names) {
+    const unique = [...new Set(names)];
+    if (unique.length <= 1)
+        return unique[0] ?? "";
+    return `${unique.slice(0, -1).join(", ")} and ${unique[unique.length - 1]}`;
+}
+export function checkMatch(uses, secretKeys) {
+    if (!uses.ok) {
+        return { ...META.match, ...undetermined(`could not read the lanes: ${uses.reason}`) };
+    }
+    const calls = uses.value.flatMap((lane) => lane.actions.filter((a) => MATCH_ACTIONS.has(a.name)).map((action) => ({ lane: lane.lane, action })));
+    if (calls.length === 0) {
+        return { ...META.match, ...ok("no lane uses match.") };
+    }
+    if (!secretKeys.includes("MATCH_PASSWORD")) {
+        return {
+            ...META.match,
+            ...warn(`${nameList(calls.map((c) => c.lane))} calls match, but MATCH_PASSWORD is not in the vault: ` +
+                "match asks for the passphrase and waits for it.", "Store `MATCH_PASSWORD` from the secrets tab.", "secrets"),
+        };
+    }
+    const writable = calls.filter((c) => c.action.args["readonly"] === false);
+    if (writable.length > 0) {
+        return {
+            ...META.match,
+            ...warn(`${nameList(writable.map((c) => c.lane))} calls match with \`readonly: false\`: it may try to ` +
+                "create certificates, which needs an Apple account interactively.", "Pass `readonly: true` so it only fetches what already exists."),
+        };
+    }
+    // `match(readonly: ENV["RO"])` arrives with no `readonly` at all: the sidecar
+    // reports literal arguments and refuses to guess at the rest. Calling that
+    // green would be the checklist claiming to know something it does not.
+    const undecided = calls.filter((c) => !("readonly" in c.action.args));
+    if (undecided.length > 0) {
+        return {
+            ...META.match,
+            ...undetermined(`MATCH_PASSWORD is stored, but \`readonly\` is not a literal in ` +
+                `${nameList(undecided.map((c) => c.lane))}: Laneyard reads literal arguments only, and will not guess.`, "Pass `readonly: true` in the call itself if that is what you mean."),
+        };
+    }
+    return { ...META.match, ...ok("MATCH_PASSWORD is stored, and every match call is readonly.") };
+}
+export function checkBlockingActions(uses) {
+    if (!uses.ok) {
+        return { ...META.blockingActions, ...undetermined(`could not read the lanes: ${uses.reason}`) };
+    }
+    const findings = uses.value.flatMap((lane) => findBlockingActions(lane.actions).map((finding) => ({ lane: lane.lane, finding })));
+    if (findings.length === 0) {
+        return { ...META.blockingActions, ...ok("no lane calls an action known to stop and ask.") };
+    }
+    return {
+        ...META.blockingActions,
+        ...warn(findings.map((f) => `${f.lane} calls ${f.finding.action}: it ${f.finding.because}`).join("; ") + ".", 
+        // The same fix stated twice reads as two different fixes.
+        [...new Set(findings.map((f) => f.finding.fix))].join(" ")),
+    };
+}
+/**
+ * The checklist itself: a table, so that adding a check is adding a row.
+ *
+ * Exported because the order it declares is the order the interface shows, and
+ * a test that checks that should read the same list.
+ */
+export const CHECKS = [
+    { ...META.repository, run: (i) => checkRepository(i.probeRepository) },
+    { ...META.dependencies, run: (i) => checkDependencies(i.dependencies) },
+    { ...META.appStoreConnect, run: (i) => checkAppStoreConnect(i.secretKeys) },
+    { ...META.match, run: (i) => checkMatch(i.uses, i.secretKeys) },
+    { ...META.blockingActions, run: (i) => checkBlockingActions(i.uses) },
+];
+/**
+ * Runs every check, and guarantees the list comes back whole.
+ *
+ * Each check already commits to not throwing. This wrapper exists because that
+ * promise is worth exactly as much as the next person to edit a check: one
+ * probe misbehaving must cost one line of the checklist, not the checklist.
+ */
+export async function runChecks(input) {
+    return Promise.all(CHECKS.map(async ({ id, title, run }) => {
+        try {
+            return await run(input);
+        }
+        catch (cause) {
+            return { id, title, state: "unknown", detail: `the check itself failed: ${reasonOf(cause)}` };
+        }
+    }));
+}

package/dist/src/logs/redact.js

@@ -0,0 +1,86 @@
+/** What a redacted value is replaced with. Fixed width, so it leaks no length. */
+const MARKER = "••••••";
+/**
+ * Values shorter than this are left alone.
+ *
+ * A two-character secret would match constantly and turn the log into confetti
+ * while hiding nothing an attacker could not guess. Refusing is more honest than
+ * pretending to protect it.
+ */
+export const MIN_LENGTH = 4;
+/**
+ * Removes secret values from a stream of text.
+ *
+ * The difficulty is not the replacement, it is the boundaries: a pseudo-terminal
+ * cuts its output wherever it likes, so a secret can arrive as `hun` then `ter2`.
+ * Replacing chunk by chunk would let it through in two pieces — and the file on
+ * disk would contain it in full.
+ *
+ * So the redactor holds back the last few characters, exactly as many as could
+ * still turn out to be the beginning of a secret, and releases them only once
+ * they cannot. `flush()` empties that buffer at the end of the run.
+ */
+/**
+ * One-shot removal, for text that is not part of the live stream.
+ *
+ * A run's error summary is stored in the database and rendered in the interface
+ * without ever passing through the stream, so it needs its own pass. Using the
+ * live `Redactor` instance here would corrupt its buffer mid-run.
+ */
+export function scrub(text, values) {
+    let out = text;
+    for (const value of [...new Set(values.filter((v) => v.length >= MIN_LENGTH))].sort((a, b) => b.length - a.length)) {
+        out = out.split(value).join(MARKER);
+    }
+    return out;
+}
+export class Redactor {
+    values;
+    longest;
+    held = "";
+    constructor(values) {
+        // Longest first: replacing "token" before "token-suffix" would leave the
+        // suffix behind in the log.
+        this.values = [...new Set(values.filter((v) => v.length >= MIN_LENGTH))].sort((a, b) => b.length - a.length);
+        this.longest = this.values.reduce((max, v) => Math.max(max, v.length), 0);
+    }
+    replaceAll(text) {
+        let out = text;
+        for (const value of this.values)
+            out = out.split(value).join(MARKER);
+        return out;
+    }
+    /**
+     * How many trailing characters could still turn into a secret.
+     *
+     * Holding a fixed window of `longest - 1` would be correct but wasteful: with
+     * a 200-character API key in the vault, every chunk would stall its last 199
+     * characters until the next one arrived, and the live terminal would lag
+     * visibly. So we keep only what is genuinely ambiguous — the longest suffix
+     * that is a proper prefix of some secret — which is usually nothing at all.
+     */
+    ambiguousTail(text) {
+        const max = Math.min(this.longest - 1, text.length);
+        for (let length = max; length > 0; length -= 1) {
+            const suffix = text.slice(text.length - length);
+            if (this.values.some((value) => value.startsWith(suffix)))
+                return length;
+        }
+        return 0;
+    }
+    /** Takes a chunk, returns the part that is safe to write out. */
+    push(chunk) {
+        if (this.values.length === 0)
+            return chunk;
+        const combined = this.replaceAll(this.held + chunk);
+        const keep = this.ambiguousTail(combined);
+        this.held = combined.slice(combined.length - keep);
+        return keep === 0 ? combined : combined.slice(0, combined.length - keep);
+    }
+    /** Releases the tail. Call once, when the stream is over. */
+    flush() {
+        const rest = this.replaceAll(this.held);
+        this.held = "";
+        return rest;
+    }
+}

package/dist/src/main.js

@@ -5,14 +5,18 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runAddCommand } from "./cli/add.js";
+import { runSecretCommand } from "./cli/secret.js";
 import { ConfigStore } from "./config/store.js";
 import { CacheStore } from "./db/cache.js";
 import { openDatabase } from "./db/open.js";
 import { RunStore } from "./db/runs.js";
+import { SecretStore } from "./db/secrets.js";
 import { buildApp } from "./server/app.js";
+import { Vault } from "./secrets/vault.js";
 import { makeInvoke } from "./sidecar/bridge.js";
 import { LaneReader } from "./sidecar/lanes.js";
-export const version = "0.1.0";
+import { UsesReader } from "./sidecar/uses.js";
+export const version = "0.2.0";
 /** Assembles the server from a data folder. */
 export async function createServerFromConfig(root) {
     const config = new ConfigStore(join(root, "config.yml"));
@@ -20,19 +24,31 @@ export async function createServerFromConfig(root) {
     if (!loaded.ok)
         throw new Error(`Unreadable configuration: ${loaded.error}`);
     const db = openDatabase(join(root, "laneyard.db"));
-    // No run can survive the shutdown of the process that carried it.
-    new RunStore(db).interruptActive();
+    // No run that had begun can survive the shutdown of the process that carried
+    // it. Queued runs never began, so they stay queued for the next start.
+    new RunStore(db).interruptInFlight();
     const cache = new CacheStore(db);
+    const vault = await Vault.open(root, new SecretStore(db));
     const app = await buildApp({
         config,
         db,
         root,
+        vault,
         lanes: async (slug, workspacePath, fastlaneDir) => {
             const resolved = await config.resolve(slug, workspacePath);
             const reader = new LaneReader(cache, makeInvoke(resolved?.settings.runtime ?? "bundle"));
             return reader.read(slug, workspacePath, fastlaneDir);
         },
+        uses: async (slug, workspacePath, fastlaneDir) => {
+            const resolved = await config.resolve(slug, workspacePath);
+            const reader = new UsesReader(cache, makeInvoke(resolved?.settings.runtime ?? "bundle"));
+            return reader.read(slug, workspacePath, fastlaneDir);
+        },
     });
+    // Anything left queued from the previous life starts moving again now. Without
+    // this, `wake()` would only ever be called from the trigger route, and three
+    // runs queued before a restart would wait for someone to trigger a fourth.
+    app.queue.wake();
     return { app, db, config };
 }
 /** Real startup, outside tests. */
@@ -69,6 +85,8 @@ function invokedDirectly() {
 const USAGE = `laneyard — a self-hosted web UI for fastlane
 
   laneyard add        adopt the project in the current directory
+  laneyard secret set NAME [--project <slug>]
+                      store a secret, its value read from standard input
   laneyard            start the server
   laneyard --version  print the version
 
@@ -113,6 +131,17 @@ if (invokedDirectly()) {
             process.exit(1);
         }
     }
+    // Above the catch-all below, which would otherwise reject it as unknown.
+    if (command === "secret") {
+        const home = homeDir();
+        await mkdir(home, { recursive: true });
+        process.exit(await runSecretCommand(home, rest, {
+            stdin: process.stdin,
+            interactive: process.stdin.isTTY === true,
+            out: (text) => process.stdout.write(text),
+            err: (text) => process.stderr.write(text),
+        }));
+    }
     if (command !== undefined) {
         process.stderr.write(`Unknown command: ${command}\n\n${USAGE}`);
         process.exit(1);

package/dist/src/runner/orchestrate.js

@@ -2,6 +2,7 @@ import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { Workspace } from "../git/workspace.js";
 import { summarizeFailure } from "../heuristics/error-summary.js";
+import { Redactor, scrub } from "../logs/redact.js";
 import { collectArtifacts } from "./artifacts.js";
 import { LiveStepTracker } from "./live-steps.js";
 import { startPty } from "./pty.js";
@@ -17,19 +18,47 @@ export async function executeRun(opts) {
     const { runId, runs, logs } = opts;
     const writer = await logs.open(runId);
     const tracker = new LiveStepTracker();
+    const redactor = new Redactor(opts.maskedValues ?? []);
+    // Redaction happens here and nowhere else: this is the single point through
+    // which every byte of output passes on its way to the file, the step tracker
+    // and the browser. Filtering further downstream would mean filtering three
+    // times, and forgetting one of them eventually.
     const emit = async (text) => {
-        const offset = await writer.append(text);
-        tracker.consume(text, offset);
-        opts.onChunk(text, offset);
+        const safe = redactor.push(text);
+        if (safe === "")
+            return;
+        const offset = await writer.append(safe);
+        tracker.consume(safe, offset);
+        opts.onChunk(safe, offset);
     };
-    const fail = async (message) => {
+    const emitRest = async () => {
+        const rest = redactor.flush();
+        if (rest === "")
+            return;
+        const offset = await writer.append(rest);
+        tracker.consume(rest, offset);
+        opts.onChunk(rest, offset);
+    };
+    // The error summary is stored in the database and rendered in the interface
+    // without passing through the stream above, so it needs its own, one-shot pass.
+    const hide = (text) => scrub(text, opts.maskedValues ?? []);
+    // Shared by every early exit, so flushing and closing the log writer cannot
+    // drift between the failure path and the two cancellation checkpoints below.
+    const finishAs = async (status, message) => {
         await emit(`\n${message}\n`);
+        await emitRest();
         await writer.close();
-        runs.finish(runId, { status: "failed", exitCode: null, errorSummary: message });
-        return { status: "failed" };
+        runs.finish(runId, { status, exitCode: null, errorSummary: hide(message) });
+        return { status };
     };
+    const fail = (message) => finishAs("failed", message);
     // --- Preparation --------------------------------------------------------
     runs.setStatus(runId, "preparing");
+    // Cancelled before it even started: no point cloning or fetching a
+    // workspace nobody wants built anymore.
+    if (opts.signal?.aborted) {
+        return finishAs("cancelled", "Cancelled");
+    }
     const workspace = new Workspace(opts.workspacePath, opts.gitUrl, opts.gitAuth);
     let commitSha;
     try {
@@ -50,6 +79,10 @@ export async function executeRun(opts) {
     catch (cause) {
         return fail(`Unreadable project settings: ${cause.message}`);
     }
+    // Cancelled during preparation: fastlane never gets to start.
+    if (opts.signal?.aborted) {
+        return finishAs("cancelled", "Cancelled");
+    }
     // --- Execution -----------------------------------------------------------
     const useBundle = settings.runtime === "bundle";
     const reportPath = join(opts.workspacePath, settings.fastlane_dir, "report.xml");
@@ -65,16 +98,20 @@ export async function executeRun(opts) {
         cwd: opts.workspacePath,
         env: {
             ...opts.env,
-            // A non-interactive run fails fast instead of freezing on an invisible prompt.
+            ...(opts.secrets ?? {}),
+            // Order matters: secrets come after opts.env so a stored secret wins over
+            // a variable that happens to exist in the server's own environment, and
+            // before these three fixed variables so no secret can override CI.
             CI: "true",
             FASTLANE_SKIP_UPDATE_CHECK: "1",
             FORCE_COLOR: "1",
         },
         onData: (chunk) => void emit(chunk),
         timeoutMs: settings.timeout_minutes * 60_000,
+        signal: opts.signal,
     });
     const outcome = await done;
-    await writer.close();
+    await emitRest();
     // --- Timeline -------------------------------------------------------------
     // Everything that follows is after-sales service: the timeline and the
     // artifacts embellish a run that's already finished. A database that
@@ -86,14 +123,27 @@ export async function executeRun(opts) {
     }
     catch (cause) {
         await emit(`\nIncomplete timeline or artifacts: ${cause.message}\n`);
+        await emitRest();
     }
+    await writer.close();
     if (outcome.exitCode === 0 && !outcome.timedOut) {
         runs.finish(runId, { status: "success", exitCode: 0, errorSummary: null });
         return { status: "success" };
     }
+    if (opts.signal?.aborted) {
+        // Checked ahead of the failure case: the SIGINT/SIGKILL escalation leaves
+        // fastlane with a nonzero exit code, which would otherwise read as a crash
+        // rather than the cancellation it actually was.
+        runs.finish(runId, {
+            status: "cancelled",
+            exitCode: outcome.exitCode,
+            errorSummary: "Cancelled",
+        });
+        return { status: "cancelled" };
+    }
     const summary = outcome.timedOut
-        ? `Run interrupted after ${settings.timeout_minutes} minutes`
-        : summarizeFailure(await logs.read(runId), outcome.exitCode);
+        ? hide(`Run interrupted after ${settings.timeout_minutes} minutes`)
+        : hide(summarizeFailure(await logs.read(runId), outcome.exitCode));
     runs.finish(runId, { status: "failed", exitCode: outcome.exitCode, errorSummary: summary });
     return { status: "failed" };
     async function recordOutcome() {