@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/conductor/wait-run-cli.js

@@ -0,0 +1,759 @@
+/**
+ * `epic-implementer wait-run` — a read-only, bounded wait on an epic run's
+ * observable state (BAPI-1469).
+ *
+ * WHY THIS EXISTS. A `/drive-epic-run` supervisor between passes has nothing to
+ * do until the run changes, and it used to fill that time by re-reading the
+ * full explain-run projection, or by inventing its own watcher. Both burn the
+ * session's context on output that has not changed. This command waits instead:
+ * it reads the run's state through the existing authenticated state route,
+ * reduces it to a small stable projection, and returns as soon as that
+ * projection changes, the run finishes, or the bounded window closes.
+ *
+ * WHAT IT IS NOT. It is not a stop path, a control verb, or an MCP tool. It
+ * performs exactly one kind of request — `GET /jira/epic-runs/runs/{id}/state`
+ * through {@link fetchEpicRunState} — and writes nothing anywhere. It never opens
+ * a database, never reads a database connection string, and never reads
+ * credentials itself: access comes only from
+ * {@link resolveConductorBridgeApiAccess}, the shared resolver every
+ * credentialed conductor command uses.
+ *
+ * THE TOKEN. Every successful result carries a `v1:` token: a short hash of the
+ * stable projection. A caller passes it back as `--since` on the next call, with
+ * the same run and the same `--ticket-key` selector. A token from a different
+ * run or selector is simply a different value — it reports `changed`, never an
+ * error. The token is not an event cursor: a `--since` mismatch says only that
+ * something changed since that token, never what, so that result carries no
+ * field history.
+ *
+ * THE WAIT. The window is governed entirely by the shared {@link boundedWait}
+ * primitive (BAPI-1104): its immediate first probe, its 15 s / 30 s polling
+ * curve, its per-probe cap, and its three-consecutive-failure transient rule.
+ * This module adds no deadline logic of its own.
+ *
+ * OUTPUT. A successful result is ONE final stdout write (one JSON line with
+ * `--json`, or one status line plus at most 20 change lines) and exits 0. A
+ * failure is exactly one bounded stderr line, no stdout, and exits 1. No
+ * failure line ever carries exception text, a response body, a header, a URL,
+ * or an access object.
+ */
+import { createHash } from "node:crypto";
+import { boundedWait as defaultBoundedWait, } from "../bounded-wait.js";
+import { ConductorBridgeApiError, fetchEpicRunState, resolveConductorBridgeApiAccess, } from "./bridge-api-client.js";
+import { ConductorValidationError } from "./errors.js";
+import { writeJsonDocument } from "./json-output.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Default wait window, in seconds. Leaves room under a 120 s host timeout. */
+export const WAIT_RUN_DEFAULT_TIMEOUT_SECONDS = 110;
+/** Largest accepted window, in seconds — the bounded-wait primitive's own ceiling. */
+export const WAIT_RUN_MAX_TIMEOUT_SECONDS = 240;
+/** At most this many change lines are rendered per result. */
+export const WAIT_RUN_MAX_CHANGES = 20;
+/** BAPI-1532 — at most this many tickets are listed in a since-mismatch `current` block. */
+export const WAIT_RUN_MAX_CURRENT_TICKETS = 20;
+/** BAPI-1532 — a listed park reason is capped at this length. */
+export const WAIT_RUN_MAX_CURRENT_REASON_CHARS = 120;
+/** Every rendered string value, identifier, and field segment is capped at this length. */
+export const WAIT_RUN_MAX_DISPLAY_CHARS = 80;
+/** Hard cap on the single stderr failure line. */
+const WAIT_RUN_MAX_ERROR_CHARS = 200;
+/** The token's exact shape: a version prefix and 16 lowercase hex characters. */
+export const WAIT_RUN_TOKEN_PATTERN = /^v1:[0-9a-f]{16}$/;
+/** Run statuses after which nothing more will happen. */
+const TERMINAL_RUN_STATUSES = new Set(["done", "abandoned"]);
+/** Fixed fallback wording for any exception this command did not expect. */
+const UNEXPECTED_FAILURE_MESSAGE = "wait-run failed unexpectedly; no run state was reported.";
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+const WAIT_RUN_VALUE_FLAGS = new Set([
+    "--epic-run-id",
+    "--ticket-key",
+    "--since",
+    "--timeout",
+]);
+const WAIT_RUN_BOOL_FLAGS = new Set(["--json", "--help"]);
+/**
+ * Parse a `--timeout` spelling into the effective window in seconds.
+ *
+ * Only a complete positive decimal integer is accepted. Values above the
+ * ceiling clamp to it; an arbitrarily long spelling clamps rather than
+ * overflowing, because its length alone proves it is above the ceiling.
+ */
+function parseTimeoutSeconds(raw) {
+    if (!/^[0-9]+$/.test(raw) || /^0+$/.test(raw)) {
+        throw new ConductorValidationError('Flag "--timeout" must be a positive whole number of seconds.');
+    }
+    const digits = raw.replace(/^0+/, "");
+    if (digits.length > 6)
+        return WAIT_RUN_MAX_TIMEOUT_SECONDS;
+    return Math.min(Number(digits), WAIT_RUN_MAX_TIMEOUT_SECONDS);
+}
+/**
+ * Parse `wait-run` flags. Every validation message is fixed text: no argv
+ * content is ever interpolated, so a hostile or secret-bearing argument cannot
+ * reach stderr.
+ */
+export function parseWaitRunArgs(argv) {
+    const values = new Map();
+    let json = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "-h" || token === "--help") {
+            return {
+                help: true,
+                epicRunId: "",
+                timeoutSeconds: WAIT_RUN_DEFAULT_TIMEOUT_SECONDS,
+                json: false,
+            };
+        }
+        if (!token.startsWith("--")) {
+            throw new ConductorValidationError("wait-run takes no positional arguments.");
+        }
+        const eq = token.indexOf("=");
+        const name = eq >= 0 ? token.slice(0, eq) : token;
+        if (WAIT_RUN_BOOL_FLAGS.has(name)) {
+            if (eq >= 0) {
+                throw new ConductorValidationError("A wait-run boolean flag does not take a value.");
+            }
+            json = true;
+            continue;
+        }
+        if (!WAIT_RUN_VALUE_FLAGS.has(name)) {
+            throw new ConductorValidationError('Unknown wait-run option. Run "epic-implementer wait-run --help" for usage.');
+        }
+        let value;
+        if (eq >= 0) {
+            value = token.slice(eq + 1);
+        }
+        else {
+            const next = argv[i + 1];
+            if (next === undefined) {
+                throw new ConductorValidationError(`Flag "${name}" requires a value.`);
+            }
+            value = next;
+            i += 1;
+        }
+        values.set(name, value);
+    }
+    const epicRunId = values.get("--epic-run-id");
+    if (epicRunId === undefined || epicRunId.trim().length === 0) {
+        throw new ConductorValidationError('Flag "--epic-run-id" is required for wait-run and must be non-empty.');
+    }
+    const parsed = {
+        help: false,
+        epicRunId: epicRunId.trim(),
+        timeoutSeconds: WAIT_RUN_DEFAULT_TIMEOUT_SECONDS,
+        json,
+    };
+    const ticketKey = values.get("--ticket-key");
+    if (ticketKey !== undefined) {
+        if (ticketKey.trim().length === 0) {
+            throw new ConductorValidationError('Flag "--ticket-key" must be non-empty when supplied.');
+        }
+        parsed.ticketKey = ticketKey.trim();
+    }
+    const since = values.get("--since");
+    if (since !== undefined) {
+        if (!WAIT_RUN_TOKEN_PATTERN.test(since)) {
+            throw new ConductorValidationError('Flag "--since" must be a token from a previous wait-run result (v1: plus 16 hex characters).');
+        }
+        parsed.since = since;
+    }
+    const timeout = values.get("--timeout");
+    if (timeout !== undefined) {
+        parsed.timeoutSeconds = parseTimeoutSeconds(timeout);
+    }
+    return parsed;
+}
+/** Command-specific help. Printing it resolves no credentials and makes no request. */
+export function getWaitRunUsage() {
+    return [
+        "Usage: epic-implementer wait-run --epic-run-id <id> [--ticket-key <key>] [--since <token>] [--timeout <seconds>] [--json]",
+        "",
+        "Read-only. Wait until an epic run's observable state changes, the run finishes,",
+        "or the window closes. Reads only the run's state route; changes nothing.",
+        "",
+        "Options:",
+        "  --epic-run-id <id>   Run id or epic key (required)",
+        "  --ticket-key <key>   Watch one ticket (plus run-level fields) instead of the whole run",
+        "  --since <token>      The token from the previous result. Reuse it only with the same",
+        "                       run and the same --ticket-key; a mismatch reports changed with the",
+        "                       bounded Current state (up to 20 tickets, parked first), not a diff",
+        `  --timeout <seconds>  Wait window (default ${WAIT_RUN_DEFAULT_TIMEOUT_SECONDS}; values above ${WAIT_RUN_MAX_TIMEOUT_SECONDS} are clamped to ${WAIT_RUN_MAX_TIMEOUT_SECONDS})`,
+        "  --json               Print one JSON line",
+        "",
+        "Outcomes (all exit 0): changed, terminal (run done or abandoned), pending",
+        "(WAIT_WINDOW_ELAPSED or UPSTREAM_TRANSIENT — run wait-run again).",
+        "Failures exit 1 with one line on stderr and nothing on stdout.",
+        "",
+        "Example:",
+        "  epic-implementer wait-run --epic-run-id BAPI-1425 --since v1:0123456789abcdef",
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Snapshot projection and token
+// ---------------------------------------------------------------------------
+/** A body the snapshot builder cannot read safely. */
+class WaitRunMalformedError extends Error {
+    constructor() {
+        super("malformed run-state response");
+        this.name = "WaitRunMalformedError";
+    }
+}
+/** `--ticket-key` names no ticket in the resolved run. */
+class WaitRunSelectorError extends Error {
+    constructor() {
+        super("ticket selector not found");
+        this.name = "WaitRunSelectorError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Absent and explicit `null` are the same observation; both become `null`. */
+function orNull(value) {
+    return value === undefined ? null : value;
+}
+/** An optional field that, when present, must be a primitive the diff can render. */
+function optionalPrimitive(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    throw new WaitRunMalformedError();
+}
+/**
+ * Recursively drop every key ending in `_at`, including inside arrays. Those
+ * keys are clocks (`next_probe_at`, `observed_at`, ...) that move without the
+ * run moving; hashing them would turn every reconciler tick into a "change".
+ */
+export function stripTimestampKeys(value) {
+    if (Array.isArray(value))
+        return value.map(stripTimestampKeys);
+    if (isRecord(value)) {
+        const out = {};
+        for (const [key, inner] of Object.entries(value)) {
+            if (key.endsWith("_at"))
+                continue;
+            out[key] = stripTimestampKeys(orNull(inner));
+        }
+        return out;
+    }
+    return value;
+}
+function compareStrings(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function buildGateSnapshot(raw) {
+    const gate = isRecord(raw) ? raw : {};
+    const observation = gate.last_observation;
+    const obs = isRecord(observation) ? observation : {};
+    const nested = isRecord(obs.observation) ? obs.observation : {};
+    return {
+        status: optionalPrimitive(gate.status),
+        attempts: optionalPrimitive(gate.attempts),
+        active_job_id: optionalPrimitive(gate.active_job_id),
+        last_observation: {
+            status: optionalPrimitive(obs.status),
+            reason: optionalPrimitive(obs.reason),
+            reason_code: optionalPrimitive(nested.reason_code ?? obs.reason_code),
+        },
+    };
+}
+function buildTicketSnapshot(raw) {
+    const gatesRaw = raw.gates;
+    if (gatesRaw !== undefined && gatesRaw !== null && !isRecord(gatesRaw)) {
+        throw new WaitRunMalformedError();
+    }
+    const gates = {};
+    if (isRecord(gatesRaw)) {
+        for (const name of Object.keys(gatesRaw).sort(compareStrings)) {
+            gates[name] = buildGateSnapshot(gatesRaw[name]);
+        }
+    }
+    return {
+        ticket_key: raw.ticket_key,
+        status: optionalPrimitive(raw.status),
+        needs_human_reason: optionalPrimitive(raw.needs_human_reason),
+        // Kept on purpose, unlike the stripped clocks: parking is itself progress.
+        parked_at: optionalPrimitive(raw.parked_at),
+        pr_number: optionalPrimitive(raw.pr_number),
+        expected_head_sha: optionalPrimitive(raw.expected_head_sha),
+        gates,
+    };
+}
+function buildJobSnapshot(raw) {
+    if (!isRecord(raw))
+        throw new WaitRunMalformedError();
+    const { id, ticket_key: ticketKey, job_type: jobType, status } = raw;
+    if (typeof id !== "number" || !Number.isFinite(id))
+        throw new WaitRunMalformedError();
+    if (typeof jobType !== "string" || typeof status !== "string")
+        throw new WaitRunMalformedError();
+    if (ticketKey !== undefined && ticketKey !== null && typeof ticketKey !== "string") {
+        throw new WaitRunMalformedError();
+    }
+    return { id, ticket_key: ticketKey ?? null, job_type: jobType, status };
+}
+/**
+ * Validate a state-route body and reduce it to the stable projection.
+ *
+ * Only the fields the projection consumes are validated: a required structure
+ * that is missing or mistyped throws {@link WaitRunMalformedError}, while an
+ * optional field that is simply absent becomes `null`. With `ticketKey`, the
+ * selector is checked against the run's COMPLETE ticket list first (throwing
+ * {@link WaitRunSelectorError} when absent), then tickets and jobs are filtered
+ * to it; run-level fields and the job-source state are always kept.
+ *
+ * `last_progress_at` is deliberately not projected. It advances only on
+ * progress today, but the token must not depend on that staying true — every
+ * field that IS progress is already projected directly.
+ */
+export function buildWaitRunSnapshot(body, ticketKey) {
+    if (!isRecord(body))
+        throw new WaitRunMalformedError();
+    const epicRun = body.epic_run;
+    if (!isRecord(epicRun) || typeof epicRun.status !== "string") {
+        throw new WaitRunMalformedError();
+    }
+    if (typeof epicRun.current_plan_version !== "number")
+        throw new WaitRunMalformedError();
+    const repairRevision = orNull(epicRun.repair_revision);
+    if (repairRevision !== null && typeof repairRevision !== "number") {
+        throw new WaitRunMalformedError();
+    }
+    const runControl = orNull(epicRun.run_control);
+    if (runControl !== null && !isRecord(runControl))
+        throw new WaitRunMalformedError();
+    const ticketRows = body.ticket_statuses;
+    if (!Array.isArray(ticketRows))
+        throw new WaitRunMalformedError();
+    for (const row of ticketRows) {
+        if (!isRecord(row) || typeof row.ticket_key !== "string" || typeof row.status !== "string") {
+            throw new WaitRunMalformedError();
+        }
+    }
+    const rows = ticketRows;
+    if (ticketKey !== undefined && !rows.some((row) => row.ticket_key === ticketKey)) {
+        throw new WaitRunSelectorError();
+    }
+    let executorJobsState = null;
+    let jobs = [];
+    const block = body.executor_jobs;
+    if (block !== undefined && block !== null) {
+        if (!isRecord(block) || typeof block.state !== "string")
+            throw new WaitRunMalformedError();
+        executorJobsState = block.state;
+        const jobRows = orNull(block.jobs);
+        if (jobRows !== null) {
+            if (!Array.isArray(jobRows))
+                throw new WaitRunMalformedError();
+            jobs = jobRows.map(buildJobSnapshot);
+        }
+    }
+    const tickets = rows
+        .filter((row) => ticketKey === undefined || row.ticket_key === ticketKey)
+        .map(buildTicketSnapshot)
+        .sort((a, b) => compareStrings(a.ticket_key, b.ticket_key));
+    const selectedJobs = jobs
+        .filter((job) => ticketKey === undefined || job.ticket_key === ticketKey)
+        .sort((a, b) => a.id - b.id);
+    return {
+        run: {
+            status: epicRun.status,
+            current_plan_version: epicRun.current_plan_version,
+            repair_revision: repairRevision,
+            run_control: stripTimestampKeys(runControl),
+        },
+        executor_jobs_state: executorJobsState,
+        tickets,
+        jobs: selectedJobs,
+    };
+}
+/** JSON with object keys sorted at every depth, so key order never moves the hash. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (isRecord(value)) {
+        const keys = Object.keys(value).sort(compareStrings);
+        return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value ?? null);
+}
+function boundedReason(value) {
+    if (typeof value !== "string")
+        return null;
+    // eslint-disable-next-line no-control-regex
+    const single = value.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim();
+    if (single === "")
+        return null;
+    return single.length > WAIT_RUN_MAX_CURRENT_REASON_CHARS
+        ? `${single.slice(0, WAIT_RUN_MAX_CURRENT_REASON_CHARS - 1)}…`
+        : single;
+}
+/**
+ * BAPI-1532 — project the snapshot already in hand onto the bounded `current`
+ * block of a since-mismatch result. No additional read is made. Parked
+ * (`needs_human`) tickets are listed first; each group keeps the snapshot's own
+ * `ticket_key` order, so two reads of unchanged state render identically.
+ */
+export function buildWaitRunCurrent(snapshot) {
+    const project = (ticket) => ({
+        ticket_key: ticket.ticket_key,
+        status: typeof ticket.status === "string" ? ticket.status : "unknown",
+        needs_human_reason: boundedReason(ticket.needs_human_reason),
+        parked_at: typeof ticket.parked_at === "string" ? ticket.parked_at : null,
+        pr_number: typeof ticket.pr_number === "number" && Number.isSafeInteger(ticket.pr_number)
+            ? ticket.pr_number
+            : null,
+    });
+    const parked = snapshot.tickets.filter((t) => t.status === "needs_human");
+    const rest = snapshot.tickets.filter((t) => t.status !== "needs_human");
+    const ordered = [...parked, ...rest];
+    const tickets = ordered.slice(0, WAIT_RUN_MAX_CURRENT_TICKETS).map(project);
+    return {
+        tickets,
+        total_count: ordered.length,
+        returned_count: tickets.length,
+        truncated: ordered.length > tickets.length,
+    };
+}
+/** `v1:` plus the first 16 hex characters of the canonical projection's SHA-256. */
+export function buildWaitRunToken(snapshot) {
+    const digest = createHash("sha256").update(canonicalJson(snapshot)).digest("hex");
+    return `v1:${digest.slice(0, 16)}`;
+}
+/** Bound a string for display: control characters removed, length capped. */
+function displayString(value) {
+    // eslint-disable-next-line no-control-regex
+    const cleaned = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+    return cleaned.length > WAIT_RUN_MAX_DISPLAY_CHARS
+        ? `${cleaned.slice(0, WAIT_RUN_MAX_DISPLAY_CHARS - 1)}…`
+        : cleaned;
+}
+function displayValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "number" || typeof value === "boolean")
+        return value;
+    return displayString(String(value));
+}
+/** Flatten a nested value into primitive leaves under dotted paths. */
+function flattenInto(out, ticketKey, path, value) {
+    if (Array.isArray(value)) {
+        value.forEach((inner, index) => flattenInto(out, ticketKey, `${path}.${index}`, inner));
+        return;
+    }
+    if (isRecord(value)) {
+        for (const key of Object.keys(value).sort(compareStrings)) {
+            flattenInto(out, ticketKey, `${path}.${key}`, value[key]);
+        }
+        return;
+    }
+    const leafKey = `${ticketKey ?? ""}\u0000${path}`;
+    out.set(leafKey, { ticketKey, field: path, value: (value ?? null) });
+}
+function flattenSnapshot(snapshot) {
+    const out = new Map();
+    flattenInto(out, null, "status", snapshot.run.status);
+    flattenInto(out, null, "current_plan_version", snapshot.run.current_plan_version);
+    flattenInto(out, null, "repair_revision", snapshot.run.repair_revision);
+    flattenInto(out, null, "run_control", snapshot.run.run_control);
+    flattenInto(out, null, "executor_jobs.state", snapshot.executor_jobs_state);
+    for (const ticket of snapshot.tickets) {
+        const { ticket_key: key, gates, ...fields } = ticket;
+        for (const [name, value] of Object.entries(fields))
+            flattenInto(out, key, name, value);
+        for (const [gate, state] of Object.entries(gates)) {
+            flattenInto(out, key, `gates.${gate}`, state);
+        }
+    }
+    for (const job of snapshot.jobs) {
+        flattenInto(out, job.ticket_key, `jobs.${job.id}.job_type`, job.job_type);
+        flattenInto(out, job.ticket_key, `jobs.${job.id}.status`, job.status);
+    }
+    return out;
+}
+function compareChanges(a, b) {
+    if (a.ticketKey !== b.ticketKey) {
+        if (a.ticketKey === null)
+            return -1;
+        if (b.ticketKey === null)
+            return 1;
+        return compareStrings(a.ticketKey, b.ticketKey);
+    }
+    return compareStrings(a.field, b.field);
+}
+/**
+ * Leaf-level changes between two normalized snapshots, ordered by ticket then
+ * field path and capped at {@link WAIT_RUN_MAX_CHANGES}.
+ *
+ * A leaf present on one side only is reported with `null` on the other, so an
+ * added or removed ticket or job never renders as a whole object. A removed
+ * job is attributed through the earlier snapshot and an added one through the
+ * later, so its ticket association survives either way.
+ */
+export function diffWaitRunSnapshots(previous, current) {
+    const before = flattenSnapshot(previous);
+    const after = flattenSnapshot(current);
+    const changed = [];
+    const keys = new Set([...before.keys(), ...after.keys()]);
+    for (const key of keys) {
+        const old = before.get(key);
+        const next = after.get(key);
+        const from = old?.value ?? null;
+        const to = next?.value ?? null;
+        if (from === to)
+            continue;
+        const anchor = (next ?? old);
+        changed.push({ ...anchor, from, to });
+    }
+    changed.sort(compareChanges);
+    const kept = changed.slice(0, WAIT_RUN_MAX_CHANGES).map((leaf) => ({
+        ticket_key: leaf.ticketKey === null ? null : displayString(leaf.ticketKey),
+        field: displayString(leaf.field),
+        from: displayValue(leaf.from),
+        to: displayValue(leaf.to),
+    }));
+    const diff = { changes: kept };
+    if (changed.length > WAIT_RUN_MAX_CHANGES)
+        diff.truncated = true;
+    return diff;
+}
+function renderValue(value) {
+    return value === null ? "null" : String(value);
+}
+/** Render a successful result: one JSON line, or one status line plus change lines. */
+export function renderWaitRunResult(result, json) {
+    if (json)
+        return JSON.stringify(result);
+    const runStatus = result.run_status === null ? "unknown" : displayString(result.run_status);
+    const token = result.token ?? "none";
+    const window = `window ${result.window_seconds}s`;
+    if (result.outcome === "pending") {
+        return `wait-run: pending ${result.reason} (run ${runStatus}, ${window}, token ${token})`;
+    }
+    if (result.outcome === "terminal") {
+        return `wait-run: terminal (run ${runStatus}, ${window}, token ${token})`;
+    }
+    if ("baseline" in result) {
+        // BAPI-1532: a labeled snapshot, stacked per ticket so a narrow terminal stays
+        // readable. It is the state NOW; what changed since the token is not reported.
+        const nil = "\u2014";
+        const lines = [
+            `wait-run: changed since the supplied token (run ${runStatus}, ${window}, token ${token})`,
+            "Current state (a snapshot, not a diff; what changed is not reported):",
+        ];
+        for (const ticket of result.current.tickets) {
+            lines.push(`  ${displayString(ticket.ticket_key)}`, `    status: ${displayString(ticket.status)}`, `    reason: ${ticket.needs_human_reason === null ? nil : displayString(ticket.needs_human_reason)}`, `    parked: ${ticket.parked_at === null ? nil : displayString(ticket.parked_at)}`, `    pr: ${ticket.pr_number === null ? nil : `#${ticket.pr_number}`}`);
+        }
+        if (result.current.truncated) {
+            lines.push(`  Showing ${result.current.returned_count} of ${result.current.total_count} tickets ` +
+                "(parked first); narrow the view with --ticket-key.");
+        }
+        return lines.join("\n");
+    }
+    const lines = [
+        `wait-run: changed (run ${runStatus}, ${window}, token ${token}` +
+            `${result.truncated ? `, first ${result.changes.length} changes shown` : ""})`,
+    ];
+    for (const change of result.changes) {
+        const subject = change.ticket_key ?? "run";
+        lines.push(`  ${subject} ${change.field}: ${renderValue(change.from)} -> ${renderValue(change.to)}`);
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Probe classification
+// ---------------------------------------------------------------------------
+/** A read that should be retried by the bounded wait rather than reported. */
+function isTransientReadFailure(err) {
+    if (!(err instanceof ConductorBridgeApiError))
+        return true;
+    if (err.kind === "network" || err.kind === "timeout" || err.kind === "server")
+        return true;
+    return err.kind === "http" && (err.status === 408 || err.status === 429);
+}
+/** Fixed operator wording for a non-retryable read failure. Only the status number is echoed. */
+function describeTerminalReadFailure(err) {
+    if (err instanceof ConductorBridgeApiError) {
+        const status = typeof err.status === "number" ? ` (HTTP ${err.status})` : "";
+        if (err.kind === "unauthorized") {
+            return `wait-run: the Bridge API refused the run-state read${status}; check credentials and repository access.`;
+        }
+        if (err.kind === "invalid-input") {
+            return "wait-run: the run identifier could not be used for a run-state read.";
+        }
+        if (err.status === 404) {
+            return "wait-run: no epic run was found for --epic-run-id (HTTP 404).";
+        }
+        return `wait-run: the run-state read failed${status}.`;
+    }
+    return UNEXPECTED_FAILURE_MESSAGE;
+}
+/** Reject promptly when the bounded wait aborts this probe, so a hung read costs one probe. */
+function untilAborted(work, signal) {
+    if (signal.aborted)
+        return Promise.reject(new Error("aborted"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new Error("aborted"));
+        signal.addEventListener("abort", onAbort, { once: true });
+        work.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+function boundedLine(text) {
+    // eslint-disable-next-line no-control-regex
+    const single = text.replace(/[\u0000-\u001f\u007f-\u009f]+/g, " ").trim();
+    return single.length > WAIT_RUN_MAX_ERROR_CHARS
+        ? `${single.slice(0, WAIT_RUN_MAX_ERROR_CHARS - 1)}…`
+        : single;
+}
+/**
+ * Run `wait-run`. Returns a process exit code: 0 for every successful outcome
+ * (`changed`, `terminal`, `pending`), 1 for any failure. Never throws.
+ */
+export async function runWaitRunCommand(argv, deps = {}) {
+    const writeStdout = deps.writeStdout ?? ((text) => writeJsonDocument(text));
+    const writeStderr = deps.writeStderr ?? ((line) => console.error(line));
+    const fail = (message) => {
+        writeStderr(`Error: ${boundedLine(message)}`);
+        return 1;
+    };
+    try {
+        let parsed;
+        try {
+            parsed = parseWaitRunArgs(argv);
+        }
+        catch (err) {
+            // Validation messages are fixed text; anything else gets the fallback.
+            return fail(err instanceof ConductorValidationError ? err.message : UNEXPECTED_FAILURE_MESSAGE);
+        }
+        if (parsed.help) {
+            if (await writeStdout(getWaitRunUsage()))
+                return 0;
+            return fail("wait-run: the help text could not be written to stdout.");
+        }
+        const resolveAccess = deps.resolveAccess ?? (() => resolveConductorBridgeApiAccess());
+        const accessResult = await resolveAccess();
+        if (!accessResult.ok) {
+            // The shared resolver's messages are fixed, secret-free text.
+            return fail(`wait-run: ${accessResult.error}`);
+        }
+        const access = accessResult.access;
+        const fetchState = deps.fetchState ?? ((a, id) => fetchEpicRunState(a, id));
+        const wait = deps.boundedWait ?? defaultBoundedWait;
+        const windowSeconds = parsed.timeoutSeconds;
+        let latestToken = parsed.since ?? null;
+        let latestRunStatus = null;
+        let baseline = null;
+        let readFailure = null;
+        const probe = async (signal) => {
+            let body;
+            try {
+                body = await untilAborted(fetchState(access, parsed.epicRunId), signal);
+            }
+            catch (err) {
+                // A transient failure is thrown back to the primitive, which counts it
+                // toward its three-in-a-row rule. Its text never reaches a result.
+                if (isTransientReadFailure(err))
+                    throw err;
+                readFailure = describeTerminalReadFailure(err);
+                return { kind: "terminal" };
+            }
+            let snapshot;
+            try {
+                snapshot = buildWaitRunSnapshot(body, parsed.ticketKey);
+            }
+            catch (err) {
+                readFailure =
+                    err instanceof WaitRunSelectorError
+                        ? "wait-run: --ticket-key does not name a ticket in this run."
+                        : err instanceof WaitRunMalformedError
+                            ? "wait-run: the run-state response was malformed."
+                            : UNEXPECTED_FAILURE_MESSAGE;
+                return { kind: "terminal" };
+            }
+            const token = buildWaitRunToken(snapshot);
+            latestToken = token;
+            latestRunStatus = snapshot.run.status;
+            // A finished run outranks any token comparison: there is nothing left to wait for.
+            if (TERMINAL_RUN_STATUSES.has(snapshot.run.status)) {
+                const value = {
+                    outcome: "terminal",
+                    token,
+                    window_seconds: windowSeconds,
+                    run_status: snapshot.run.status,
+                };
+                return { kind: "observation", ready: true, value };
+            }
+            if (baseline === null) {
+                if (parsed.since !== undefined && parsed.since !== token) {
+                    const value = {
+                        outcome: "changed",
+                        token,
+                        baseline: "since",
+                        window_seconds: windowSeconds,
+                        run_status: snapshot.run.status,
+                        current: buildWaitRunCurrent(snapshot),
+                    };
+                    return { kind: "observation", ready: true, value };
+                }
+                baseline = { snapshot, token };
+                return { kind: "observation", ready: false };
+            }
+            if (token !== baseline.token) {
+                const diff = diffWaitRunSnapshots(baseline.snapshot, snapshot);
+                const value = {
+                    outcome: "changed",
+                    token,
+                    window_seconds: windowSeconds,
+                    run_status: snapshot.run.status,
+                    changes: diff.changes,
+                    ...(diff.truncated ? { truncated: true } : {}),
+                };
+                return { kind: "observation", ready: true, value };
+            }
+            return { kind: "observation", ready: false };
+        };
+        const outcome = await wait({
+            budgetMs: windowSeconds * 1000,
+            probe,
+            ...(deps.waitDeps ? { deps: deps.waitDeps } : {}),
+        });
+        let result;
+        if (outcome.state === "ready") {
+            result = outcome.result;
+        }
+        else if (outcome.state === "pending") {
+            result = {
+                outcome: "pending",
+                reason: outcome.reason,
+                token: latestToken,
+                window_seconds: windowSeconds,
+                run_status: latestRunStatus,
+            };
+        }
+        else {
+            return fail(readFailure ?? UNEXPECTED_FAILURE_MESSAGE);
+        }
+        if (await writeStdout(renderWaitRunResult(result, parsed.json)))
+            return 0;
+        return fail("wait-run: the result could not be written to stdout.");
+    }
+    catch {
+        return fail(UNEXPECTED_FAILURE_MESSAGE);
+    }
+}