@dna113p/machines 0.3.3 → 0.3.5

package/dist/src/run-ui.d.ts

@@ -0,0 +1,62 @@
+import { type RunStatusRecord } from "./run-status.ts";
+/**
+ * `machine ui`: a local page that shows every published run as it happens,
+ * with its Machine's graph, and the project's own panels beside them. It reads
+ * the run-status directory and answers a waiting run through its inbox, as
+ * `machine respond` does; nothing else in the page changes anything.
+ */
+export interface RunUiOptions {
+    /** The run-status directory. */
+    readonly directory: string;
+    /** The project whose `.machines/ui.json` names panels; its name heads the page. */
+    readonly projectDir: string;
+    readonly port?: number;
+    /** How often the directory is read for changes. */
+    readonly pollMilliseconds?: number;
+}
+export interface RunUi {
+    readonly url: string;
+    close(): Promise<void>;
+}
+/** A run as the page shows it: `lost` when its record says running or waiting and its process is gone. */
+export type UiRun = Omit<RunStatusRecord, "status"> & {
+    readonly status: RunStatusRecord["status"] | "lost";
+};
+/** What a panel command prints: a few lines a person can take in at a glance. */
+export interface UiPanel {
+    readonly title: string;
+    readonly summary?: string;
+    readonly items: readonly UiPanelItem[];
+    readonly error?: string;
+    readonly checkedAt?: string;
+}
+export interface UiPanelItem {
+    readonly text: string;
+    readonly detail?: string;
+    /** Colours the item: `bad` and `warn` draw the eye, `active` is work under way. */
+    readonly status?: "ok" | "warn" | "bad" | "active" | "idle";
+    readonly href?: string;
+    readonly at?: string;
+}
+interface PanelSource {
+    readonly title: string;
+    readonly command: readonly string[];
+    readonly refreshSeconds: number;
+}
+export declare const defaultUiPort = 4777;
+/** The nearest directory at or above `start` that has a `.machines` directory, or `start` itself. */
+export declare function uiProjectDir(start: string): string;
+/** Every published run, with runs whose process is gone shown as lost. */
+export declare function uiRuns(directory: string, isAlive?: (pid: number) => boolean): UiRun[];
+/**
+ * Reads `.machines/ui.json`: `{ "panels": [{ "title", "command": [...], "refreshSeconds"? }] }`.
+ * A missing file is no panels; a malformed one is one panel saying what is wrong.
+ */
+export declare function readPanelSources(projectDir: string): {
+    sources: PanelSource[];
+    error?: string;
+};
+/** Turns a panel command's output into a panel, or says why it could not. */
+export declare function parsePanelOutput(title: string, stdout: string): UiPanel;
+export declare function startRunUi(options: RunUiOptions): Promise<RunUi>;
+export {};

package/dist/src/run-ui.js

@@ -0,0 +1,258 @@
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { basename, dirname, join, resolve } from "node:path";
+import { respondToRun } from "./run-inbox.js";
+import { runUiPage } from "./run-ui-page.js";
+import { isProcessAlive, readRunStatuses } from "./run-status.js";
+export const defaultUiPort = 4777;
+const panelTimeoutMilliseconds = 30_000;
+const maxPanelItems = 50;
+/** The nearest directory at or above `start` that has a `.machines` directory, or `start` itself. */
+export function uiProjectDir(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, ".machines")) && statSync(join(current, ".machines")).isDirectory())
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return resolve(start);
+        current = parent;
+    }
+}
+/** Every published run, with runs whose process is gone shown as lost. */
+export function uiRuns(directory, isAlive = isProcessAlive) {
+    return readRunStatuses(directory)
+        .map((record) => ((record.status === "running" || record.status === "waiting") && !isAlive(record.pid)
+        ? { ...record, status: "lost" }
+        : record))
+        .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+}
+/**
+ * Reads `.machines/ui.json`: `{ "panels": [{ "title", "command": [...], "refreshSeconds"? }] }`.
+ * A missing file is no panels; a malformed one is one panel saying what is wrong.
+ */
+export function readPanelSources(projectDir) {
+    const file = join(projectDir, ".machines", "ui.json");
+    if (!existsSync(file))
+        return { sources: [] };
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (!Array.isArray(parsed.panels))
+            throw new Error("panels must be an array");
+        const sources = parsed.panels.map((panel, index) => {
+            const { title, command, refreshSeconds } = (panel ?? {});
+            if (typeof title !== "string" || title.trim() === "")
+                throw new Error(`panels[${index}].title must be a non-empty string`);
+            if (!Array.isArray(command) || command.length === 0 || !command.every((part) => typeof part === "string")) {
+                throw new Error(`panels[${index}].command must be a non-empty array of strings`);
+            }
+            if (refreshSeconds !== undefined && (typeof refreshSeconds !== "number" || !(refreshSeconds >= 1))) {
+                throw new Error(`panels[${index}].refreshSeconds must be a number of at least 1`);
+            }
+            return { title, command, refreshSeconds: refreshSeconds ?? 10 };
+        });
+        return { sources };
+    }
+    catch (cause) {
+        return { sources: [], error: `${file}: ${cause instanceof Error ? cause.message : String(cause)}` };
+    }
+}
+/** Turns a panel command's output into a panel, or says why it could not. */
+export function parsePanelOutput(title, stdout) {
+    const parsed = JSON.parse(stdout);
+    if (parsed === null || typeof parsed !== "object" || !Array.isArray(parsed.items)) {
+        throw new Error("the command must print a JSON object with an items array");
+    }
+    const statuses = new Set(["ok", "warn", "bad", "active", "idle"]);
+    const text = (value, limit) => typeof value === "string" && value.trim() !== "" ? value.slice(0, limit) : undefined;
+    const items = parsed.items.slice(0, maxPanelItems).flatMap((item) => {
+        const entry = (item ?? {});
+        const line = text(entry.text, 300);
+        if (line === undefined)
+            return [];
+        const href = text(entry.href, 2000);
+        return [{
+                text: line,
+                ...(text(entry.detail, 600) === undefined ? {} : { detail: text(entry.detail, 600) }),
+                ...(typeof entry.status === "string" && statuses.has(entry.status) ? { status: entry.status } : {}),
+                // Only web links: a panel never gets the page to open anything else.
+                ...(href !== undefined && /^https?:\/\//u.test(href) ? { href } : {}),
+                ...(text(entry.at, 40) !== undefined && !Number.isNaN(Date.parse(entry.at)) ? { at: entry.at } : {}),
+            }];
+    });
+    return { title, ...(text(parsed.summary, 300) === undefined ? {} : { summary: text(parsed.summary, 300) }), items };
+}
+export async function startRunUi(options) {
+    const { directory, projectDir } = options;
+    const token = randomBytes(24).toString("hex");
+    const poll = options.pollMilliseconds ?? 1_000;
+    const clients = new Set();
+    const panels = new Map();
+    let port = 0;
+    let last = "";
+    const refreshPanels = () => {
+        const { sources, error } = readPanelSources(projectDir);
+        if (error !== undefined) {
+            panels.set("\0config", { panel: { title: "ui.json", items: [], error }, checkedAt: Date.now(), running: false });
+        }
+        else
+            panels.delete("\0config");
+        const wanted = new Set(sources.map((source) => source.title));
+        for (const title of panels.keys())
+            if (title !== "\0config" && !wanted.has(title))
+                panels.delete(title);
+        for (const source of sources) {
+            const known = panels.get(source.title);
+            if (known?.running || (known !== undefined && Date.now() - known.checkedAt < source.refreshSeconds * 1_000))
+                continue;
+            const entry = { panel: known?.panel ?? { title: source.title, items: [] }, checkedAt: Date.now(), running: true };
+            panels.set(source.title, entry);
+            execFile(source.command[0], source.command.slice(1), {
+                cwd: projectDir, timeout: panelTimeoutMilliseconds, maxBuffer: 4 * 1024 * 1024, encoding: "utf8",
+            }, (failure, stdout, stderr) => {
+                let panel;
+                try {
+                    if (failure)
+                        throw new Error((stderr.trim() || failure.message).split("\n").slice(-3).join(" "));
+                    panel = parsePanelOutput(source.title, stdout);
+                }
+                catch (cause) {
+                    panel = { ...entry.panel, error: cause instanceof Error ? cause.message : String(cause) };
+                }
+                panels.set(source.title, { panel: { ...panel, checkedAt: new Date().toISOString() }, checkedAt: Date.now(), running: false });
+                broadcast();
+            });
+        }
+    };
+    const snapshot = () => ({
+        project: { name: basename(projectDir), dir: projectDir },
+        directory,
+        runs: uiRuns(directory),
+        panels: [...panels.values()].map((entry) => entry.panel),
+    });
+    const broadcast = (force = false) => {
+        const state = snapshot();
+        const text = JSON.stringify(state);
+        if (!force && text === last)
+            return;
+        last = text;
+        for (const client of clients)
+            client.write(`data: ${text}\n\n`);
+    };
+    const timer = setInterval(() => {
+        refreshPanels();
+        broadcast();
+    }, poll);
+    timer.unref();
+    // A quiet connection is closed by some proxies and browsers; a comment keeps it open.
+    const heartbeat = setInterval(() => { for (const client of clients)
+        client.write(": ping\n\n"); }, 15_000);
+    heartbeat.unref();
+    const server = createServer((request, response) => {
+        void handle(request, response).catch((cause) => {
+            if (!response.headersSent)
+                send(response, 500, { error: cause instanceof Error ? cause.message : String(cause) });
+            else
+                response.end();
+        });
+    });
+    async function handle(request, response) {
+        // Another site can make the browser send to this port, but not with this host name: a page served
+        // from a name that resolves here (DNS rebinding) is refused, and only the page itself holds the token.
+        const host = request.headers.host ?? "";
+        if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`)
+            return send(response, 421, { error: "unexpected host" });
+        const url = new URL(request.url ?? "/", `http://${host}`);
+        if (request.method === "GET" && url.pathname === "/") {
+            response.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-store",
+                "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+                "x-content-type-options": "nosniff",
+            });
+            response.end(runUiPage(token));
+            return;
+        }
+        if (request.method === "GET" && url.pathname === "/api/state")
+            return send(response, 200, snapshot());
+        if (request.method === "GET" && url.pathname === "/api/events") {
+            response.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+            clients.add(response);
+            response.write(`data: ${JSON.stringify(snapshot())}\n\n`);
+            request.on("close", () => clients.delete(response));
+            return;
+        }
+        if (request.method === "POST" && url.pathname === "/api/respond") {
+            if (request.headers["x-machines-ui"] !== token)
+                return send(response, 403, { error: "missing or wrong page token" });
+            const body = await readBody(request);
+            const { runId, requestId, response: text, question } = body;
+            if (typeof runId !== "string" || typeof requestId !== "string" || typeof text !== "string" || text.trim() === "") {
+                return send(response, 400, { error: "runId, requestId, and a non-empty response are required" });
+            }
+            const answer = question === true ? { type: "question", text } : text;
+            try {
+                await respondToRun({ directory, runId, requestId, response: answer });
+            }
+            catch (cause) {
+                return send(response, 409, { error: cause instanceof Error ? cause.message : String(cause) });
+            }
+            broadcast(true);
+            return send(response, 200, { ok: true });
+        }
+        send(response, 404, { error: "not found" });
+    }
+    const start = options.port ?? defaultUiPort;
+    // The first free port from the one asked for: a second page for another project is not an error.
+    for (let candidate = start;; candidate += 1) {
+        try {
+            await new Promise((resolveListen, rejectListen) => {
+                server.once("error", rejectListen);
+                server.listen(candidate, "127.0.0.1", () => {
+                    server.off("error", rejectListen);
+                    resolveListen();
+                });
+            });
+            port = candidate;
+            break;
+        }
+        catch (cause) {
+            if (cause.code !== "EADDRINUSE" || candidate - start >= 20 || options.port === 0)
+                throw cause;
+        }
+    }
+    const address = server.address();
+    if (address !== null && typeof address === "object")
+        port = address.port;
+    refreshPanels();
+    return {
+        url: `http://127.0.0.1:${port}/`,
+        close: () => new Promise((resolveClose) => {
+            clearInterval(timer);
+            clearInterval(heartbeat);
+            for (const client of clients)
+                client.end();
+            server.close(() => resolveClose());
+        }),
+    };
+}
+function send(response, status, body) {
+    response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    response.end(JSON.stringify(body));
+}
+async function readBody(request) {
+    let text = "";
+    for await (const chunk of request) {
+        text += String(chunk);
+        if (text.length > 64 * 1024)
+            throw new Error("request body too large");
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}

package/dist/src/run-viewer.d.ts

@@ -0,0 +1,57 @@
+import { type RunStatusRecord } from "./run-status.ts";
+import { type RunWatch } from "./run-watch.ts";
+export { readRunStatuses, runSessionId, runStatusDirectory } from "./run-status.ts";
+export type { RunStatusAgent, RunStatusHuman, RunStatusLimit, RunStatusRecord } from "./run-status.ts";
+export { statePaths } from "./run-graph.ts";
+export type { RunGraph, RunGraphEdge, RunGraphState, RunTrailStep } from "./run-graph.ts";
+export { readRunWatches } from "./run-watch.ts";
+export type { RunWatch } from "./run-watch.ts";
+/** How long a settled or lost run stays with its viewers before it drops out. */
+export declare const settledRunVisibleMilliseconds = 30000;
+/** One surface that shows runs: a coding-agent session, a status line, a browser tab. */
+export interface RunViewer {
+    /** Shows the runs this session owns. Its watch list is kept under the same id. */
+    readonly sessionId: string;
+    /** Absolute project directory; shows unowned runs working in it or below it. */
+    readonly projectDir?: string;
+    /** What the session asked to watch; shows the top-level runs an entry names, whoever owns them. */
+    readonly watches?: readonly RunWatch[];
+}
+export interface ViewerRunOptions {
+    readonly now?: number;
+    /** Keeps settled and lost runs however long ago they stopped. */
+    readonly all?: boolean;
+    readonly isAlive?: (pid: number) => boolean;
+}
+/**
+ * How a waiting run's Human request is answered: by `machine respond` with
+ * these two ids, or only through the program that hosts the run.
+ */
+export type RunAnswer = {
+    readonly via: "respond";
+    readonly runId: string;
+    readonly requestId: string;
+} | {
+    readonly via: "host";
+};
+/** A published record as one viewer shows it. */
+export interface ViewerRun extends Omit<RunStatusRecord, "status"> {
+    /** `lost` when the record says running or waiting and its process is gone. */
+    readonly status: RunStatusRecord["status"] | "lost";
+    /** Why the viewer shows it; the first that holds of owned, project, and watched. */
+    readonly shown: "owned" | "project" | "watched";
+    /** Present while the run waits on a request that something can answer. */
+    readonly answer?: RunAnswer;
+}
+/**
+ * The runs one viewer shows: the runs its session owns, unowned runs working
+ * inside its project, and runs it watches. Sub-runs are never shown, and a
+ * settled or lost run drops out after `settledRunVisibleMilliseconds`. Runs
+ * that can still change come first, then the most recently updated; records
+ * that tie keep the order they were given in.
+ *
+ * Pure apart from the default process-liveness probe. `claude/statusline.mjs`
+ * cannot load this module and carries a copy of the selection;
+ * tests/run-viewer.test.ts keeps the two in step.
+ */
+export declare function runsForViewer(records: readonly RunStatusRecord[], viewer: RunViewer, options?: ViewerRunOptions): ViewerRun[];

package/dist/src/run-viewer.js

@@ -0,0 +1,66 @@
+import { isProcessAlive } from "./run-status.js";
+import { isWithinDirectory, runWatchMatches } from "./run-watch.js";
+// The package exports this module as `@dna113p/machines/run-status`: what an
+// application needs to draw its own widgets for published runs. It only reads;
+// the publisher and the watch-list writer stay in the runtime.
+export { readRunStatuses, runSessionId, runStatusDirectory } from "./run-status.js";
+export { statePaths } from "./run-graph.js";
+export { readRunWatches } from "./run-watch.js";
+/** How long a settled or lost run stays with its viewers before it drops out. */
+export const settledRunVisibleMilliseconds = 30_000;
+/**
+ * The runs one viewer shows: the runs its session owns, unowned runs working
+ * inside its project, and runs it watches. Sub-runs are never shown, and a
+ * settled or lost run drops out after `settledRunVisibleMilliseconds`. Runs
+ * that can still change come first, then the most recently updated; records
+ * that tie keep the order they were given in.
+ *
+ * Pure apart from the default process-liveness probe. `claude/statusline.mjs`
+ * cannot load this module and carries a copy of the selection;
+ * tests/run-viewer.test.ts keeps the two in step.
+ */
+export function runsForViewer(records, viewer, options = {}) {
+    const { now = Date.now(), all = false, isAlive = isProcessAlive } = options;
+    const visible = [];
+    for (const record of records) {
+        // Sub-runs belong to the run that started them, not to the session.
+        if (record.parent !== undefined)
+            continue;
+        const shown = shownBecause(record, viewer);
+        if (shown === undefined)
+            continue;
+        const updatedAt = Date.parse(record.updatedAt);
+        const recorded = record.status === "running" || record.status === "waiting";
+        // A run that stopped reporting without finishing has lost its process.
+        const lost = recorded && !isAlive(record.pid);
+        const active = recorded && !lost;
+        if (!active && !all && now - updatedAt > settledRunVisibleMilliseconds)
+            continue;
+        const status = lost ? "lost" : record.status;
+        const answer = status === "waiting" ? runAnswer(record) : undefined;
+        visible.push({ run: { ...record, status, shown, ...(answer === undefined ? {} : { answer }) }, active, updatedAt });
+    }
+    visible.sort((left, right) => Number(right.active) - Number(left.active) || right.updatedAt - left.updatedAt);
+    return visible.map(({ run }) => run);
+}
+function shownBecause(record, viewer) {
+    // An owned run is its owner's: the project it works in shows it to nobody else.
+    if (record.owner !== undefined) {
+        if (record.owner === viewer.sessionId)
+            return "owned";
+    }
+    else if (viewer.projectDir !== undefined && isWithinDirectory(record.cwd, viewer.projectDir)) {
+        return "project";
+    }
+    // A run the session asked to watch is shown whoever owns it and wherever it works.
+    return viewer.watches?.some((watch) => runWatchMatches(watch, record)) === true ? "watched" : undefined;
+}
+function runAnswer(record) {
+    if (record.human === undefined)
+        return undefined;
+    if (record.answeredBy === "host")
+        return { via: "host" };
+    // A record from before requests had ids says nothing about how it is answered.
+    const { requestId } = record.human;
+    return requestId === undefined ? undefined : { via: "respond", runId: record.id, requestId };
+}

package/dist/src/run-watch.d.ts

@@ -18,7 +18,9 @@ export declare function readRunWatches(directory: string, sessionId: string): Ru
 /** Replaces a session's watch list; an empty one removes its file. */
 export declare function writeRunWatches(directory: string, sessionId: string, watches: readonly RunWatch[]): void;
 /** Whether a watch names a run. A sub-run is never watched: it is its parent's detail. */
-export declare function runWatchMatches(watch: RunWatch, record: RunStatusRecord): boolean;
+export declare function runWatchMatches(watch: RunWatch, record: Pick<RunStatusRecord, "id" | "label" | "cwd" | "parent">): boolean;
+/** Whether a path is a directory or inside it. Only absolute paths say where they are. */
+export declare function isWithinDirectory(path: string, directory: string): boolean;
 /** Checks and normalizes what `machine watch` was given. */
 export declare function runWatch(input: RunWatch): RunWatch;
 export declare function sameRunWatch(left: RunWatch, right: RunWatch): boolean;

package/dist/src/run-watch.js

@@ -52,18 +52,22 @@ export function writeRunWatches(directory, sessionId, watches) {
 export function runWatchMatches(watch, record) {
     if (record.parent !== undefined)
         return false;
-    if ("dir" in watch) {
-        if (!isAbsolute(record.cwd))
-            return false;
-        const cwd = resolve(record.cwd);
-        return cwd === watch.dir || cwd.startsWith(watch.dir.endsWith(sep) ? watch.dir : `${watch.dir}${sep}`);
-    }
+    if ("dir" in watch)
+        return isWithinDirectory(record.cwd, watch.dir);
     if (record.id.startsWith(watch.text))
         return true;
     // The label must start with the whole text, not with a longer word that begins like it.
     const next = record.label?.startsWith(watch.text) ? record.label.slice(watch.text.length) : undefined;
     return next !== undefined && !/^[\p{L}\p{N}_-]/u.test(next);
 }
+/** Whether a path is a directory or inside it. Only absolute paths say where they are. */
+export function isWithinDirectory(path, directory) {
+    if (!isAbsolute(path) || !isAbsolute(directory))
+        return false;
+    const outer = resolve(directory);
+    const inner = resolve(path);
+    return inner === outer || inner.startsWith(outer.endsWith(sep) ? outer : `${outer}${sep}`);
+}
 /** Checks and normalizes what `machine watch` was given. */
 export function runWatch(input) {
     if ("dir" in input) {

package/docs/architecture.md

@@ -61,6 +61,8 @@ MCP server ────┘       ↑
 | `src/discovery-worker.ts` | Fresh metadata imports in disposable workers |
 | `src/host.ts` | One child run, IPC, Human request identity, owned process termination, run-status publication for the run |
 | `src/session.ts` | Shared Pi/MCP run lifecycle, snapshots, response handling, retention, shutdown |
+| `src/run-status.ts`, `src/run-watch.ts` | The run-status directory rule, one record per published run, session identity, and each session's watch list |
+| `src/run-viewer.ts` | Which published runs one viewer shows; exported with the readers as `@dna113p/machines/run-status` |
 | `src/cli.ts` | Command parsing, terminal progress, source inspection |
 | `pi-extension/index.ts` | Pi tools, widgets, notifications, native input presentation |
 | `mcp/server.ts` | MCP schemas, tool results, and the optional HTML resource |
@@ -120,6 +122,14 @@ only way to answer it, its record says so, and `machine respond` refuses it. See
 A session's watch list changes only which published runs its status line shows.
 It gives no ownership of a run and no way to answer one.
 
+Which runs a viewer shows is one rule, `runsForViewer` in `src/run-viewer.ts`:
+`machine runs --for` prints its answer, and `@dna113p/machines/run-status`
+exports it with the readers, so that an application draws its own widgets
+without a second copy. It selects and orders; presentation stays with whatever
+draws. The standalone status line cannot load it and carries a tested copy, as
+it does of the directory rule. See
+[Integrations](integrations.md#drawing-your-own-widgets).
+
 Closing a session terminates active and starting hosts. Host termination includes
 ordinary descendants in the host's owned process group on POSIX and process-tree
 termination on Windows. Deliberately detached processes can escape normal ownership;

package/docs/authoring.md

@@ -101,6 +101,10 @@ The Machine owns this loop. An Agent runner only returns an allowed outcome; it
 does not decide destination states. Add verification Operations where the workflow
 has a concrete condition to check.
 
+When designing verification and repair routes, follow
+[Checks the Machine owns](../skills/machine-builder/SKILL.md#checks-the-machine-owns)
+for the checks and evidence the workflow must own.
+
 ### Handling a usage limit in the Machine
 
 By default an Agent state never sees its provider's usage limit: the launcher
@@ -471,6 +475,15 @@ Options:
   `MACHINES_AGENT_MODEL` / `MACHINES_AGENT_EFFORT`. The `env` option overrides
   matching parent variables. With no setting, Codex selects its configured values;
   effort must be supported by the selected model.
+- `serviceTier`: selects a Codex service tier, for example
+  `codexAgent("codex", [], { serviceTier: "fast" })` for Fast mode or
+  `codexAgent("codex", [], { serviceTier: "ultrafast" })` for Ultrafast. Overrides
+  `CODEX_SERVICE_TIER` (including values supplied through `env`); when neither
+  is set, the runner leaves Codex's configured tier unchanged. The built-in
+  preset also accepts `CODEX_SERVICE_TIER=fast` or `CODEX_SERVICE_TIER=ultrafast`.
+  Both are opt-in; Machines does not enable either tier by default. Supported
+  tiers depend on the installed CLI, model, and account. See the
+  [Codex configuration reference](https://developers.openai.com/codex/config-reference#service_tier).
 - `output`: `stream` (default) writes agent messages and stderr to the terminal;
   `capture` keeps them off the terminal and includes final prose in the event's
   `message`. Both modes report activity to observers.