@mgiles/perk 3.2.0 → 3.3.0

package/extension/delivery/address.ts

@@ -0,0 +1,295 @@
+// The review-feedback finalization feature (the address half of the delivery pair), Pi-free.
+//
+// One entry point — `finalizeAddress` — owns the ordering and failure semantics of the
+// submit-then-resolve loop: pre-effect refusal (empty batch) → publish (composing the sibling
+// submit feature's `publishVerified` — one-way import, no cycle) → resolve → request↔row
+// correlation → verified-success session record → the bounded conflict decision. The decision
+// timing is deliberately DIFFERENT from `/submit`'s: it runs only after full corroborated
+// resolve success — a resolve failure never burns an attempt.
+//
+// Uncertainty is a first-class value: one module-private correlation pass derives a
+// per-requested-thread fate — `resolved` | `failed` (with the positively-reported reply fact) |
+// `unknown` (no row: the effect may have happened, verification failed) — consumed by (a) the
+// safe-retry derivation (a reply is retained ONLY on a positive not-posted report) and (b) the
+// ok-arm corroboration guard (a nominal-success envelope that fails to corroborate every
+// requested thread is `published_partial`, never recorded/terminated — contracts §8.52: "full
+// success" = corroborated per-thread success). The two unresolved states are DISTINCT
+// discriminants — `published_partial` (rows known, retry derivable) and `published_unverified`
+// (no per-thread claim) — so retry-without-rows is unrepresentable. Refusals (`bad_input`,
+// `planning_session`) are adapter shapes — they never enter the outcome union.
+
+import type {
+  ReviewBatchCounts,
+  ReviewBatchRecord,
+  WorkflowSession,
+} from "../session/workflowSession.ts";
+import {
+  type ConflictFollowUp,
+  decideConflictFollowUp,
+  type PublishDeps,
+  type PublishedChange,
+  publishVerified,
+} from "./submit.ts";
+
+export interface ThreadInput {
+  thread_id: string;
+  comment?: string;
+}
+
+/** One per-thread outcome row from the resolve port's batch result. */
+export interface ThreadResultRow {
+  thread_id: string;
+  success: boolean;
+  comment_added: boolean;
+  error?: string | null;
+}
+
+/** One external resolve attempt: full rows, a partial report with rows, or an uncertain fail. */
+export type ResolveThreadsAttempt =
+  | { ok: true; rows: ThreadResultRow[] }
+  | { ok: false; kind: "partial"; rows: ThreadResultRow[]; message: string; errorType: string }
+  | { ok: false; kind: "failed"; message: string; errorType: string };
+
+/** The resolve port — production = `perk pr resolve-threads --json --batch`. */
+export type ResolveThreads = (threads: ThreadInput[]) => Promise<ResolveThreadsAttempt>;
+
+/** The finalization input (the adapter's decoded tool params). */
+export interface AddressFinalization {
+  threads: ThreadInput[];
+  pr?: number;
+  counts?: ReviewBatchCounts;
+}
+
+export interface FinalizeAddressDeps extends PublishDeps {
+  resolve: ResolveThreads;
+  session: WorkflowSession;
+}
+
+export type FinalizeAddressOutcome =
+  | { kind: "empty_batch"; message: string }
+  | {
+      kind: "not_published";
+      /** The raw publisher failure — the adapter reproduces today's scope-"submit" report. */
+      publishMessage: string;
+      message: string;
+      errorType: string;
+    }
+  | {
+      kind: "published_partial";
+      change: PublishedChange;
+      resolveMessage: string;
+      message: string;
+      errorType: string;
+      results: ThreadResultRow[];
+      resolvedThreadIds: string[];
+      /** Possibly empty — the adapter omits retry_threads when empty (today's wire). */
+      retryThreads: ThreadInput[];
+    }
+  | {
+      kind: "published_unverified";
+      change: PublishedChange;
+      resolveMessage: string;
+      message: string;
+      errorType: string;
+    }
+  | {
+      kind: "completed";
+      change: PublishedChange;
+      results: ThreadResultRow[];
+      resolvedThreadIds: string[];
+      conflict: ConflictFollowUp;
+    };
+
+/** One requested thread's correlated fate (module-private — never exported). */
+type ThreadFate =
+  | { kind: "resolved" }
+  | { kind: "failed"; replyPosted: boolean }
+  | { kind: "unknown" };
+
+/**
+ * The one correlation pass: requested ids deduped by FIRST occurrence; the row lookup is built
+ * `new Map(rows.map(...))` so a duplicate row's LAST observation wins (today's exact
+ * precedence — safe on the partial/retry path, where the envelope already failed; the ok-arm
+ * corroboration guard additionally refuses contradictory duplicates via `contradictedIds`).
+ * Rows for never-requested ids are ignored.
+ */
+function correlateFates(
+  requested: ThreadInput[],
+  rows: ThreadResultRow[],
+): Map<string, { input: ThreadInput; fate: ThreadFate }> {
+  const byId = new Map(rows.map((row) => [row.thread_id, row]));
+  const fates = new Map<string, { input: ThreadInput; fate: ThreadFate }>();
+  for (const input of requested) {
+    if (fates.has(input.thread_id)) continue;
+    const row = byId.get(input.thread_id);
+    const fate: ThreadFate =
+      row === undefined
+        ? { kind: "unknown" }
+        : row.success
+          ? { kind: "resolved" }
+          : { kind: "failed", replyPosted: row.comment_added };
+    fates.set(input.thread_id, { input, fate });
+  }
+  return fates;
+}
+
+/**
+ * Requested ids whose rows DISAGREE on `success` (version-skew evidence). A contradictory
+ * duplicate must never corroborate a nominal success — last-row precedence would erase the
+ * failure observation before the guard runs — so the ok-arm treats these as uncorroborated
+ * and retries them with the reply stripped (both the resolve and the reply outcome are
+ * unknowable from contradictory evidence).
+ */
+function contradictedIds(requested: ThreadInput[], rows: ThreadResultRow[]): Set<string> {
+  const requestedIds = new Set(requested.map((input) => input.thread_id));
+  const lastSuccess = new Map<string, boolean>();
+  const contradicted = new Set<string>();
+  for (const row of rows) {
+    if (!requestedIds.has(row.thread_id)) continue;
+    const prior = lastSuccess.get(row.thread_id);
+    if (prior !== undefined && prior !== row.success) contradicted.add(row.thread_id);
+    lastSuccess.set(row.thread_id, row.success);
+  }
+  return contradicted;
+}
+
+/**
+ * The only safe automatic retry batch, derived from the fates: resolved threads are omitted; a
+ * reply is retained ONLY on a positive not-posted report (`failed` with `replyPosted: false`);
+ * an `unknown` fate is outcome-unknown, so its reply is stripped rather than risked twice. A
+ * `contradicted` id (ok-arm only) is likewise outcome-unknown: retried with the reply stripped.
+ */
+function retryFromFates(
+  fates: Map<string, { input: ThreadInput; fate: ThreadFate }>,
+  contradicted: Set<string> = new Set(),
+): ThreadInput[] {
+  const retry: ThreadInput[] = [];
+  for (const [id, { input, fate }] of fates) {
+    const effective: ThreadFate = contradicted.has(id) ? { kind: "unknown" } : fate;
+    if (effective.kind === "resolved") continue;
+    if (effective.kind === "failed" && !effective.replyPosted && input.comment !== undefined) {
+      retry.push({ thread_id: input.thread_id, comment: input.comment });
+    } else {
+      retry.push({ thread_id: input.thread_id });
+    }
+  }
+  return retry;
+}
+
+const EMPTY_BATCH_MESSAGE = "no threads to finalize (pass { threads: [{thread_id, comment?}] })";
+
+const INSPECT_GUIDANCE =
+  "Inspect the resolution failure before retrying; omit any reply that may already have posted.";
+const RETRY_GUIDANCE =
+  "Re-run finalize_address with only details.retry_threads; successful rows were omitted " +
+  "and replies already reported as posted were stripped.";
+
+function resolveFailedMessage(resolveMessage: string, retryable: boolean): string {
+  return (
+    `propagation succeeded, but thread resolution failed: ${resolveMessage}. ` +
+    `The submit already succeeded. ${retryable ? RETRY_GUIDANCE : INSPECT_GUIDANCE}`
+  );
+}
+
+/** All success rows, in row order (the wire's `resolved_thread_ids` — row-derived, not fates). */
+function resolvedIdsOf(rows: ThreadResultRow[]): string[] {
+  return rows.filter((row) => row.success).map((row) => row.thread_id);
+}
+
+/**
+ * Publish committed address fixes, then resolve their review threads. Ordering policy: the
+ * empty refusal fires before any port; a failed publish returns with no resolve call, no
+ * session writes, and no counter activity; the batch record and the conflict decision happen
+ * ONLY after corroborated full resolve success (never-burn-an-attempt). The record's
+ * classification is ignored — the session seam owns loudness.
+ */
+export async function finalizeAddress(
+  deps: FinalizeAddressDeps,
+  input: AddressFinalization,
+): Promise<FinalizeAddressOutcome> {
+  if (input.threads.length === 0) {
+    return { kind: "empty_batch", message: EMPTY_BATCH_MESSAGE };
+  }
+
+  const published = await publishVerified(deps);
+  if (!published.ok) {
+    return {
+      kind: "not_published",
+      publishMessage: published.message,
+      message:
+        `propagation failed; threads were NOT resolved — ${published.message}. ` +
+        "Fix the publication failure, then re-run finalize_address.",
+      errorType: published.errorType,
+    };
+  }
+  const change = published.change;
+
+  const resolved = await deps.resolve(input.threads);
+  if (!resolved.ok && resolved.kind === "failed") {
+    return {
+      kind: "published_unverified",
+      change,
+      resolveMessage: resolved.message,
+      message: resolveFailedMessage(resolved.message, false),
+      errorType: resolved.errorType,
+    };
+  }
+
+  const rows = resolved.rows;
+  const fates = correlateFates(input.threads, rows);
+  const retryThreads = retryFromFates(fates);
+  const resolvedThreadIds = resolvedIdsOf(rows);
+
+  if (!resolved.ok) {
+    return {
+      kind: "published_partial",
+      change,
+      resolveMessage: resolved.message,
+      message: resolveFailedMessage(resolved.message, retryThreads.length > 0),
+      errorType: resolved.errorType,
+      results: rows,
+      resolvedThreadIds,
+      retryThreads,
+    };
+  }
+
+  // The ok-arm corroboration guard: a nominal-success envelope must corroborate EVERY requested
+  // thread (missing/failed/duplicate-CONTRADICTING rows under version skew route to partial —
+  // nothing recorded, nothing termination-eligible).
+  const contradicted = contradictedIds(input.threads, rows);
+  const uncorroborated = [...fates.entries()].filter(
+    ([id, { fate }]) => fate.kind !== "resolved" || contradicted.has(id),
+  ).length;
+  if (uncorroborated > 0) {
+    const guardRetry = retryFromFates(fates, contradicted);
+    const resolveMessage = `the resolve report did not corroborate ${uncorroborated} requested thread(s)`;
+    return {
+      kind: "published_partial",
+      change,
+      resolveMessage,
+      message: resolveFailedMessage(resolveMessage, guardRetry.length > 0),
+      errorType: "partial_failure",
+      results: rows,
+      resolvedThreadIds,
+      retryThreads: guardRetry,
+    };
+  }
+
+  const record: ReviewBatchRecord = {
+    pr: input.pr ?? null,
+    counts: input.counts ?? null,
+    resolved_thread_ids: resolvedThreadIds,
+    at: new Date().toISOString(),
+  };
+  // Classification deliberately ignored: the seam reports its own read-back warnings, and a
+  // recording miss must never sink an already-corroborated resolve success.
+  deps.session.apply({ kind: "record-review-batch", record });
+
+  return {
+    kind: "completed",
+    change,
+    results: rows,
+    resolvedThreadIds,
+    conflict: decideConflictFollowUp(change, deps.attempts),
+  };
+}

package/extension/delivery/ci.ts

@@ -0,0 +1,355 @@
+// The CI-execution feature (the Run→Report half of Run→Report→Fix→Verify), Pi-free.
+//
+// A deterministic check runner over the project's configured `[[ci.checks]]` rows: it selects,
+// orders, glob-gates, runs, and REPORTS — it never edits, fixes, or loops. Checks execute
+// CONCURRENTLY (each row must be independently runnable; declared order governs the report
+// order, not execution order — sequencing that matters belongs inside one row's command, e.g.
+// `cmd1 && cmd2`). The caller owns the entire fix loop; this feature is a stateless oracle
+// invoked once per run (the `devrun` discipline: "run and report", never "run and fix").
+//
+// "Read-only" here is a property of THIS MODULE and its OUTPUT, not a sandbox: the check
+// commands run with full shell access through the injected `RunConfiguredCheck` port. The
+// untrusted-config scope gate (`decideCiScope`) and the output-isolation wrapping live with the
+// adapter that composes the ports; the feature's own defenses are output routing (full output
+// persisted through the `PersistCheckOutput` port, capped model-visible slice) and never-throw
+// per-check folding.
+
+import type { CiCheck } from "../substrate/config.ts";
+import { capForModel, DEFAULT_MODEL_VISIBLE_CAP } from "../substrate/modelVisible.ts";
+
+/** One configured check's outcome. `executed` carries no `passed` field — passed ≡
+ * `exitCode === 0` (derived where needed, so a contradiction is unrepresentable); `skipped`
+ * only ever arises from a declared glob, so `glob` is required. */
+export type CiCheckOutcome =
+  | {
+      kind: "executed";
+      name: string;
+      command: string;
+      exitCode: number;
+      /** The capped, model-visible output (route-don't-relay — the full output was persisted
+       * through the port). */
+      shown: string;
+      /** The port-minted opaque location of the persisted full output (`null` = persistence
+       * failed; the failure rides `error`). */
+      outputPath: string | null;
+      bytesTotal: number;
+      bytesShown: number;
+      truncated: boolean;
+      error?: string;
+    }
+  | { kind: "skipped"; name: string; command: string; glob: string };
+
+/** The typed run outcome. `invalid_selection` carries the selection diagnostic (back-pressure
+ * is feature meaning); `completed.passed` counts skipped checks as passed. Refusals and
+ * tool-boundary decode failures are adapter shapes — they never enter this union. */
+export type CiRunOutcome =
+  | { kind: "not_configured" }
+  | { kind: "invalid_selection"; message: string }
+  | {
+      kind: "completed";
+      scope: "all" | "subset";
+      passed: boolean;
+      checks: readonly CiCheckOutcome[];
+    };
+
+/** The per-check display state of the typed live-progress stream. */
+export type CiProgressState = "running" | "passed" | "failed" | "skipped";
+
+export interface CiProgressEntry {
+  readonly name: string;
+  readonly state: CiProgressState;
+}
+
+/**
+ * The delivery-specific typed progress event union. No per-event check identity — configured
+ * names are not unique; the ORDERED entries snapshot is the correlation surface. `run_started`
+ * fires synchronously before any check launches (skips already resolved); one `check_settled`
+ * per executed-check completion. Every emission deep-copies the entry objects.
+ */
+export type CiProgressEvent =
+  | { readonly kind: "run_started"; readonly entries: readonly CiProgressEntry[] }
+  | { readonly kind: "check_settled"; readonly entries: readonly CiProgressEntry[] };
+
+/** A single deterministic command execution outcome (output = trimmed stdout + "\n" + stderr). */
+export interface CiExecOutcome {
+  code: number;
+  output: string;
+}
+
+/** The semantic port "run this configured check" (one production adapter: the Pi shell runner). */
+export type RunConfiguredCheck = (
+  check: CiCheck,
+  opts: { signal?: AbortSignal },
+) => Promise<CiExecOutcome>;
+
+/** "Persist this check's full output and return its opaque location" — throws on failure. */
+export type PersistCheckOutput = (checkName: string, output: string) => string;
+
+/** The semantic port "changed files vs trunk"; `null` = unknown (the fail-open sentinel — the
+ * run then skips nothing). One production adapter: the git composition in the Pi adapter. */
+export type ObserveChangedFiles = (opts: {
+  signal?: AbortSignal;
+}) => Promise<ReadonlySet<string> | null>;
+
+export type CiScope = "run" | "confirm" | "refuse";
+
+/**
+ * Decide how to treat project-supplied CI. Pure (the load-bearing safety boundary):
+ *   - `[ci] trusted` (committed config), `--allow-project-ci`, or a per-session latch ⇒ "run"
+ *     (trust runs on EVERY surface, overriding the headless refuse below)
+ *   - else with UI ⇒ "confirm" (ask the human)
+ *   - else (headless, no trust/flag) ⇒ "refuse" (fail closed)
+ */
+export function decideCiScope(args: {
+  hasUI: boolean;
+  allowFlag: boolean;
+  approved: boolean;
+  trusted: boolean;
+}): CiScope {
+  if (args.trusted || args.allowFlag || args.approved) return "run";
+  return args.hasUI ? "confirm" : "refuse";
+}
+
+/**
+ * Run one configured check deterministically: run the port, persist the FULL combined output
+ * through the `PersistCheckOutput` port, cap the model-visible output. Never throws — a
+ * run-port throw becomes `exitCode: -1` with the error captured; a persistence throw folds to
+ * the same failure shape (`error` = the thrown message, `outputPath: null`) with the exit code
+ * intact.
+ */
+async function runOneCheck(
+  check: CiCheck,
+  runCheck: RunConfiguredCheck,
+  persistOutput: PersistCheckOutput,
+  signal?: AbortSignal,
+): Promise<CiCheckOutcome> {
+  let outcome: CiExecOutcome;
+  try {
+    outcome = await runCheck(check, { signal });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      kind: "executed",
+      name: check.name,
+      command: check.command,
+      exitCode: -1,
+      shown: message,
+      outputPath: null,
+      bytesTotal: 0,
+      bytesShown: 0,
+      truncated: false,
+      error: message,
+    };
+  }
+
+  // Persist the full output through the port: a returned string IS the location; ANY throw
+  // folds to the failure shape (the port owns write+verify semantics — no post-write probe).
+  let outputPath: string | null = null;
+  let writeError: string | undefined;
+  try {
+    outputPath = persistOutput(check.name, outcome.output);
+  } catch (err) {
+    writeError = err instanceof Error ? err.message : String(err);
+  }
+
+  // Tail-keep: pytest/tsc failure summaries live at the END of the output, so the model-visible
+  // slice keeps the last `cap` bytes; the persisted location still holds the full output.
+  const capped = capForModel(outcome.output, DEFAULT_MODEL_VISIBLE_CAP, outputPath, "tail");
+  return {
+    kind: "executed",
+    name: check.name,
+    command: check.command,
+    exitCode: outcome.code,
+    shown: capped.shown,
+    outputPath,
+    bytesTotal: capped.bytesTotal,
+    bytesShown: capped.bytesShown,
+    truncated: capped.truncated,
+    ...(writeError ? { error: writeError } : {}),
+  };
+}
+
+/**
+ * Dependency-free glob match. `glob` is a single comma-separated pattern string; the path matches
+ * iff it matches ANY pattern. Each pattern is translated to an anchored RegExp: regex metachars
+ * escaped, then `**` → `.*` (crosses directories) and `*` → `[^/]*` (one segment). A slash-free
+ * pattern is matched against the path's BASENAME (so `*.py` gates any `.py` at any depth, the
+ * gitignore/fnmatch rule); a pattern containing `/` is matched against the full repo-relative
+ * POSIX path.
+ */
+function matchesGlob(path: string, glob: string): boolean {
+  for (const raw of glob.split(",")) {
+    const pattern = raw.trim();
+    if (!pattern) continue;
+    // Escape regex metachars, including `*` (restored below to glob semantics).
+    const escaped = pattern.replace(/[.+^${}()|[\]\\*]/g, "\\$&");
+    // Restore glob stars in one pass (so the single-`*` rule never clobbers a `**`): the escaped
+    // forms are `\*\*` (→ `.*`, crosses dirs) and `\*` (→ `[^/]*`, one segment).
+    const body = escaped.replace(/\\\*\\\*|\\\*/g, (m) => (m === "\\*\\*" ? ".*" : "[^/]*"));
+    const subject = pattern.includes("/") ? path : (path.split("/").pop() ?? path);
+    if (new RegExp(`^${body}$`).test(subject)) return true;
+  }
+  return false;
+}
+
+/** A skipped-check outcome: not executed because its glob matched no changed file (vs trunk). */
+function skippedResult(check: CiCheck, glob: string): CiCheckOutcome {
+  return { kind: "skipped", name: check.name, command: check.command, glob };
+}
+
+export interface RunCiChecksOpts {
+  checks: CiCheck[];
+  only?: string;
+  signal?: AbortSignal;
+}
+
+export interface RunCiChecksDeps {
+  runCheck: RunConfiguredCheck;
+  /** Persist one check's full output; the returned string is the opaque location this feature
+   * treats as data (a throw folds to the check's failure shape). */
+  persistOutput: PersistCheckOutput;
+  observeChangedFiles: ObserveChangedFiles;
+  /** Optional typed live-progress sink. Failure-owned here: each call is wrapped in try/catch,
+   * so a throwing sink cannot affect the run (the callback contract is synchronous `void`). */
+  onProgress?: (event: CiProgressEvent) => void;
+}
+
+/**
+ * Run the selected checks (or all when `only` is omitted) CONCURRENTLY and report every result
+ * in the config's DECLARED order — declared order governs the report, not execution, so each
+ * `[[ci.checks]]` row must be independently runnable (sequencing that matters belongs inside one
+ * row's command, e.g. `cmd1 && cmd2`). `only` accepts one name or a comma-separated list — an
+ * EXACT name match wins before any comma-splitting (so a configured name that itself contains a
+ * comma or surrounding whitespace stays selectable), and each requested name selects the FIRST
+ * declared row with that name (duplicates never broaden a selection); the selected rows still
+ * run concurrently and report in declared order. Empty checks ⇒ inert `not_configured`; an
+ * unknown (or missing) `only` name ⇒ an actionable `invalid_selection` listing the available
+ * names (back-pressure, not a silent failure). Does NOT stop at the first failure.
+ * `passed = every executed check exited 0` (skips count as passed).
+ *
+ * **Change-scoped gating (run-all path only).** When any selected check declares a `glob`, the
+ * changed-file set (vs trunk) is observed ONCE — before any check launches — and each globbed
+ * check is skipped when no changed file matches (never a failure). A check with no `glob`
+ * always runs; an explicit `only` always runs (no glob gate, no observation); a fail-open
+ * `null` observation runs everything (never skip on uncertainty). No observation happens when
+ * no selected row is globbed.
+ */
+export async function runCiChecks(
+  opts: RunCiChecksOpts,
+  deps: RunCiChecksDeps,
+): Promise<CiRunOutcome> {
+  const checks = opts.checks;
+  if (checks.length === 0) {
+    return { kind: "not_configured" };
+  }
+  const names = checks.map((c) => c.name);
+
+  // Explicit selection: `only` is one configured name or a comma-separated list. An exact name
+  // match is tried FIRST (compatibility: any accepted name — even one containing a comma or
+  // surrounding whitespace — stays selectable); only a non-matching string is comma-split.
+  // Selected rows run in DECLARED order (not argument order); no glob gate, no observation.
+  let selected = checks;
+  let explicit = false;
+  if (opts.only !== undefined) {
+    const exact = checks.find((c) => c.name === opts.only);
+    const requested = exact
+      ? [exact.name]
+      : opts.only
+          .split(",")
+          .map((s) => s.trim())
+          .filter((s) => s.length > 0);
+    if (requested.length === 0) {
+      return {
+        kind: "invalid_selection",
+        message: `no check names given; available: ${names.join(", ")}`,
+      };
+    }
+    const unknown = requested.filter((n) => !names.includes(n));
+    if (unknown.length > 0) {
+      return {
+        kind: "invalid_selection",
+        message: `unknown check${unknown.length > 1 ? "s" : ""} '${unknown.join("', '")}'; available: ${names.join(", ")}`,
+      };
+    }
+    // Each requested name selects the FIRST declared row with that name (the pre-concurrency
+    // `find` semantics): duplicate names never broaden an explicit selection into extra rows
+    // racing on the same name-keyed persisted-output target.
+    const wanted = new Set(requested);
+    const seen = new Set<string>();
+    selected = checks.filter((c) => {
+      if (!wanted.has(c.name) || seen.has(c.name)) return false;
+      seen.add(c.name);
+      return true;
+    });
+    explicit = true;
+  }
+
+  // The changed-set observation (compute-once, before run_started and before any launch);
+  // a throwing observer folds to the same fail-open `null` its contract already means.
+  const gate = !explicit && selected.some((c) => c.glob);
+  let changed: ReadonlySet<string> | null = null;
+  if (gate) {
+    try {
+      changed = await deps.observeChangedFiles({ signal: opts.signal });
+    } catch {
+      changed = null;
+    }
+  }
+
+  // Skip a globbed check only when we KNOW the changed set (changed !== null) and nothing matches.
+  const skipsByGlob = (check: CiCheck): boolean => {
+    if (explicit || !check.glob || changed === null) return false;
+    const glob = check.glob;
+    return ![...changed].some((f) => matchesGlob(f, glob));
+  };
+
+  // Typed live progress: one ordered state entry per selected check (skips resolve
+  // synchronously), a `run_started` emission before any launch, one `check_settled` per
+  // executed-check completion. Every emission deep-copies the entries — a retained earlier
+  // event never mutates, and a sink mutating its received entries cannot affect later events
+  // or the outcome. Progress is cosmetic: a throwing sink is contained (the callback
+  // contract is synchronous `void`).
+  const onProgress = deps.onProgress;
+  const states = selected.map((check): { name: string; state: CiProgressState } => ({
+    name: check.name,
+    state: skipsByGlob(check) ? "skipped" : "running",
+  }));
+  const emit = (kind: CiProgressEvent["kind"]): void => {
+    if (!onProgress) return;
+    try {
+      onProgress({
+        kind,
+        entries: states.map((entry) => ({ name: entry.name, state: entry.state })),
+      });
+    } catch {
+      // Progress must never break the run.
+    }
+  };
+  emit("run_started");
+
+  // Launch every non-skipped check at once; `map` + `Promise.all` keeps `results` in declared
+  // order regardless of completion order, and `runOneCheck` never throws, so `Promise.all`
+  // cannot reject. Wall time is the MAX of the check durations, not the sum.
+  const results: CiCheckOutcome[] = await Promise.all(
+    selected.map((check, i) => {
+      const glob = check.glob;
+      if (glob !== undefined && skipsByGlob(check)) {
+        return Promise.resolve(skippedResult(check, glob));
+      }
+      return runOneCheck(check, deps.runCheck, deps.persistOutput, opts.signal).then((result) => {
+        const entry = states[i];
+        if (entry) {
+          entry.state = result.kind === "executed" && result.exitCode === 0 ? "passed" : "failed";
+        }
+        emit("check_settled");
+        return result;
+      });
+    }),
+  );
+  return {
+    kind: "completed",
+    scope: explicit ? "subset" : "all",
+    passed: results.every((c) => c.kind === "skipped" || c.exitCode === 0),
+    checks: results,
+  };
+}