@brainervirus/workit-core 2.3.0 → 2.5.0

package/src/forge/pr-ops.ts

@@ -0,0 +1,450 @@
+// `workit pr create` and `workit pr merge` (design §2.1 S11): forge writes with
+// a SHA bound before the call and verified after it.
+//
+// create: the branch must already be pushed (remote tip == local head); that
+// SHA is bound, an open PR/MR for the branch is reused (`created: false`),
+// and success means the forge reports the bound SHA as the PR head. The
+// `pr.created` ledger row is what `ledger check --pr` resolves through (S13).
+//
+// merge: three independent gates, all required:
+//   1. the S10 status document reads READY (required checks green, no
+//      conflicts, threads, review or draft blockers);
+//   2. an accepted S13 verdict for that exact head (fresh or carried), unless
+//      the workspace grants `merge: true`;
+//   3. the `merge` grant (autonomy.ts `requireGrant`; S16 fills the defaults).
+// The merge call carries the head SHA (GitHub `sha=`, GitLab `sha=`), so a
+// head that moves after the gates refuses instead of merging unverified code.
+// --delete-branch deletes with a lease on that same SHA.
+import { requireGrant } from "../autonomy";
+import { isProtectedTarget } from "../core/branch";
+import { vcsConfig } from "../core/vcs-config";
+import { deleteRemoteBranch } from "../git/ops";
+import { spawnSync } from "node:child_process";
+import { currentBranch, fetchRefs, GIT_TIMEOUTS, remoteRefTip, resolveRef } from "../git/rev";
+import {
+  appendObserved,
+  checkVerdicts,
+  readLedger,
+  type LedgerActor,
+  type VerdictCheck,
+} from "../ledger";
+import { buildStatusDoc, selectPr, type PrStatusDoc } from "./report";
+import type { ResolvedForge } from "./resolve";
+import { failure, success, type ForgeResult, type MergeMethod, type PrRef } from "./types";
+
+export type Sleep = (ms: number) => Promise<void>;
+
+/** Post-verification retries: the forge may take a moment to show a new head or merge. */
+const VERIFY_DELAYS_MS = [1_000, 2_000, 4_000];
+
+const noun = (resolved: ResolvedForge): string =>
+  resolved.forge.kind === "github" ? "pull request" : "merge request";
+
+const grantBlocked = (decision: Extract<ReturnType<typeof requireGrant>, { allowed: false }>) =>
+  failure("blocked", decision.error, decision.unblock);
+
+// ---------------------------------------------------------------------------
+// create
+
+export type CreateInput = {
+  base: string;
+  title: string;
+  body: string;
+  draft: boolean;
+  actor: LedgerActor;
+};
+
+export type CreateOutcome = {
+  number: number;
+  url: string;
+  branch: string;
+  base: string;
+  head: string;
+  created: boolean;
+  draft: boolean;
+  recorded: { id: string } | { error: string };
+};
+
+/**
+ * `--fill`: the title and body from the branch's commits on top of the base
+ * (fetched first). One commit gives its subject and body; several give the
+ * oldest subject and a list of every subject.
+ */
+export function fillFromCommits(
+  cwd: string,
+  resolved: ResolvedForge,
+  base: string,
+): ForgeResult<{ title: string; body: string }> {
+  const tracking = `refs/remotes/${resolved.baseRemote}/${base}`;
+  if (!base.startsWith("-"))
+    fetchRefs(cwd, resolved.baseRemote, [`+refs/heads/${base}:${tracking}`]);
+  const from = resolveRef(cwd, tracking) ?? resolveRef(cwd, `refs/heads/${base}`);
+  if (!from)
+    return failure(
+      "not_found",
+      `base ${base} is not available locally`,
+      `git fetch ${resolved.baseRemote} ${base}`,
+    );
+  const log = spawnSync(
+    "git",
+    ["log", "--reverse", "--no-merges", "--format=%s%x1f%b%x1e", `${from}..HEAD`],
+    {
+      cwd,
+      encoding: "utf8",
+      timeout: GIT_TIMEOUTS.local,
+      killSignal: "SIGKILL",
+    },
+  );
+  const commits = (log.status === 0 ? log.stdout : "")
+    .split("\x1e")
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [subject = "", body = ""] = entry.split("\x1f");
+      return { subject: subject.trim(), body: body.trim() };
+    });
+  if (commits.length === 0)
+    return failure(
+      "invalid_input",
+      `no commits on top of ${base}; nothing to describe`,
+      "pass --title <t>",
+    );
+  if (commits.length === 1) return success({ title: commits[0].subject, body: commits[0].body });
+  return success({
+    title: commits[0].subject,
+    body: commits.map((commit) => `- ${commit.subject}`).join("\n"),
+  });
+}
+
+/** The pushed head of the current branch, bound before any forge write. */
+export function boundSource(
+  cwd: string,
+  resolved: ResolvedForge,
+): ForgeResult<{ branch: string; sha: string }> {
+  const branch = currentBranch(cwd);
+  if (!branch) return failure("invalid_input", "HEAD is detached; check out the PR branch");
+  const sha = resolveRef(cwd, `refs/heads/${branch}`);
+  if (!sha) return failure("not_found", `branch ${branch} has no commit`);
+  const remote = remoteRefTip(cwd, resolved.remote, `refs/heads/${branch}`);
+  if (!remote.ok) return failure(remote.code, remote.error);
+  if (remote.sha !== sha)
+    return failure(
+      "blocked",
+      remote.sha === null
+        ? `not_pushed: ${branch} is not on ${resolved.remote}`
+        : `not_pushed: ${resolved.remote}/${branch} is at ${remote.sha.slice(0, 12)}, local ${branch} is at ${sha.slice(0, 12)}`,
+      "workit git push",
+    );
+  return success({ branch, sha });
+}
+
+async function verifiedHead(
+  resolved: ResolvedForge,
+  branch: string,
+  sha: string,
+  first: PrRef,
+  sleep: Sleep,
+): Promise<ForgeResult<PrRef>> {
+  let ref = first;
+  for (const delay of [0, ...VERIFY_DELAYS_MS]) {
+    if (ref.headSha === sha) return success(ref);
+    if (delay) await sleep(delay);
+    const found = resolved.forge.findPr(branch, {
+      owner: resolved.headRepo.split("/")[0] ?? null,
+      projectId: resolved.headProjectId,
+      sha,
+    });
+    if (!found.ok) return found;
+    if (found.data && found.data.number === first.number) ref = found.data;
+  }
+  return ref.headSha === sha
+    ? success(ref)
+    : failure(
+        "failed",
+        `head_unverified: ${noun(resolved)} #${first.number} reports head ${ref.headSha?.slice(0, 12) ?? "(none)"}, not the pushed ${sha.slice(0, 12)}`,
+        `workit pr status --pr ${first.number}`,
+      );
+}
+
+export async function createPullRequest(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: CreateInput,
+  sleep: Sleep,
+): Promise<ForgeResult<CreateOutcome>> {
+  const grant = requireGrant(cwd, "pr");
+  if (!grant.allowed) return grantBlocked(grant);
+  const source = boundSource(cwd, resolved);
+  if (!source.ok) return source;
+  const { branch, sha } = source.data;
+  if (branch === input.base)
+    return failure(
+      "invalid_input",
+      `the PR source and base are both ${branch}`,
+      "pass --base <branch>",
+    );
+
+  const existing = resolved.forge.findPr(branch, {
+    owner: resolved.headRepo.split("/")[0] ?? null,
+    projectId: resolved.headProjectId,
+    sha,
+  });
+  if (!existing.ok) return existing;
+  let created = false;
+  let ref: PrRef;
+  if (existing.data && existing.data.state === "open") ref = existing.data;
+  else {
+    const made = resolved.forge.createPr({
+      head: branch,
+      headRepo: resolved.headRepo,
+      headProjectId: resolved.headProjectId,
+      base: input.base,
+      title: input.title,
+      body: input.body,
+      draft: input.draft,
+    });
+    if (!made.ok) return made;
+    ref = made.data;
+    created = true;
+  }
+  const verified = await verifiedHead(resolved, branch, sha, ref, sleep);
+  if (!verified.ok) return verified;
+  const row = appendObserved(cwd, {
+    type: "pr.created",
+    actor: input.actor,
+    branch,
+    head: sha,
+    pr: ref.number,
+    base: input.base,
+    url: ref.url,
+    forge: resolved.forge.kind,
+    repo: resolved.forge.repo,
+    created,
+  });
+  return success({
+    number: ref.number,
+    url: ref.url,
+    branch,
+    base: input.base,
+    head: sha,
+    created,
+    draft: input.draft,
+    recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// merge
+
+export type MergeInput = {
+  pr: number | null;
+  method: MergeMethod;
+  deleteBranch: boolean;
+  actor: LedgerActor;
+};
+
+export type MergeOutcome = {
+  number: number;
+  url: string;
+  branch: string;
+  base: string;
+  head: string;
+  method: MergeMethod;
+  mergeSha: string | null;
+  verdict: { required: boolean; accepted: boolean; verdictId: string | null };
+  grant: { source: "autonomy" | "host_authority" };
+  deletedBranch: boolean | { error: string };
+  recorded: { id: string } | { error: string };
+};
+
+/** Why `pr merge` refused, for the envelope `data` (agents branch on `reason`). */
+export type MergeRefusal = {
+  reason:
+    | "grant_required"
+    | "not_ready"
+    | "needs_verdict"
+    | "head_mismatch"
+    | "already_merged"
+    | "closed"
+    | "protected_branch";
+  next?: string;
+  blockers?: string[];
+  verdict?: Pick<VerdictCheck, "head" | "accepted" | "authors">;
+};
+
+export type MergeResult =
+  | { ok: true; data: MergeOutcome }
+  | {
+      ok: false;
+      code: "blocked" | "failed" | "unavailable" | "not_found" | "busy" | "invalid_input";
+      error: string;
+      unblock?: string;
+      refusal?: MergeRefusal;
+    };
+
+const refuse = (error: string, unblock: string, refusal: MergeRefusal): MergeResult => ({
+  ok: false,
+  code: "blocked",
+  error,
+  unblock,
+  refusal,
+});
+
+const NEXT_HINTS: Record<string, string> = {
+  RESOLVE_CONFLICTS: "rebase onto the base, resolve, then workit git push --force-with-lease",
+  REBASE: "rebase onto the base, then workit git push --force-with-lease",
+  RESOLVE_THREADS: "address and resolve the open review threads (workit pr status lists them)",
+  FIX_CI:
+    "fix the failing checks (workit pr status shows the log tails), push, then workit ci wait",
+  WAITING_CI: "workit ci wait",
+  ADDRESS_REVIEW: "address the requested changes",
+  REVIEW: "get the required review",
+  MARK_READY: "mark the PR ready for review",
+  IN_MERGE_QUEUE: "the PR is already in the merge queue",
+  NOT_MERGEABLE: "workit pr status  # the forge reports it cannot merge yet",
+};
+
+export async function mergePullRequest(
+  cwd: string,
+  resolved: ResolvedForge,
+  input: MergeInput,
+  sleep: Sleep,
+): Promise<MergeResult> {
+  const grant = requireGrant(cwd, "merge");
+  if (!grant.allowed) return refuse(grant.error, grant.unblock, { reason: "grant_required" });
+
+  const number = selectPr(cwd, resolved, { pr: input.pr });
+  if (!number.ok) return number;
+  const status = resolved.forge.prStatus(number.data);
+  if (!status.ok) return status;
+  const built = buildStatusDoc(cwd, resolved, status.data, { logLines: 0, behind: false });
+  if (!built.ok) return built;
+  const doc: PrStatusDoc = built.data;
+  const label = `${resolved.forge.kind === "github" ? "PR #" : "MR !"}${doc.number}`;
+  if (doc.state === "merged")
+    return refuse(
+      `already_merged: ${label} is already merged`,
+      `workit verify-delivery merged --pr ${doc.number}`,
+      {
+        reason: "already_merged",
+      },
+    );
+  if (doc.state === "closed")
+    return refuse(`closed: ${label} is closed`, "reopen it on the forge first", {
+      reason: "closed",
+    });
+  if (doc.next !== "READY")
+    return refuse(
+      `not_ready: ${label} is ${doc.next} (${doc.blockers.join(", ") || doc.next.toLowerCase()})`,
+      NEXT_HINTS[doc.next] ?? "workit pr status",
+      { reason: "not_ready", next: doc.next, blockers: doc.blockers },
+    );
+
+  const branch = doc.head.branch;
+  const head = doc.head.sha;
+  // --delete-branch never deletes a protected branch, the base, or the
+  // default target (a develop -> main release PR must keep develop). Refused
+  // before merging, so the caller decides without a half-done delivery.
+  if (input.deleteBranch) {
+    const resolvedVcs = vcsConfig("resolve", cwd);
+    const defaultTarget =
+      resolvedVcs.ok === false ? null : String(resolvedVcs.defaultTargetBranch ?? "") || null;
+    const lower = branch.toLowerCase();
+    const reason = isProtectedTarget(cwd, branch)
+      ? "is protected by the workspace branch policy"
+      : lower === doc.base.toLowerCase()
+        ? "is the PR base"
+        : defaultTarget !== null && lower === defaultTarget.toLowerCase()
+          ? "is the default target branch"
+          : null;
+    if (reason)
+      return refuse(
+        `protected_branch: --delete-branch would delete ${branch}, which ${reason}; workit never deletes it`,
+        `workit pr merge${input.pr ? ` --pr ${doc.number}` : ""} --method ${input.method}  # without --delete-branch`,
+        { reason: "protected_branch" },
+      );
+  }
+  let verdict: MergeOutcome["verdict"] = {
+    required: grant.requireVerdict,
+    accepted: false,
+    verdictId: null,
+  };
+  if (grant.requireVerdict) {
+    const ledger = readLedger(cwd);
+    if (!ledger.ok) return ledger;
+    const check = checkVerdicts(cwd, branch, ledger.value.rows);
+    const summary = { head: check.head, accepted: check.accepted, authors: check.authors };
+    if (check.head !== head)
+      return refuse(
+        `head_mismatch: the verdict check reads ${branch} at ${check.head?.slice(0, 12) ?? "(missing)"} but ${label} is at ${head.slice(0, 12)}`,
+        `git fetch && git switch ${branch} && git merge --ff-only @{u}  # then re-verify that head`,
+        { reason: "head_mismatch", verdict: summary },
+      );
+    if (!check.accepted.accepted)
+      return refuse(
+        `NEEDS_VERDICT: ${label} has no accepted independent verdict for ${head.slice(0, 12)} (${check.accepted.reasons.join(", ")})`,
+        `an independent session verifies the head and runs: workit ledger verdict verified --how "<what was exercised>" --branch ${branch}`,
+        { reason: "needs_verdict", verdict: summary },
+      );
+    verdict = {
+      required: true,
+      accepted: true,
+      verdictId: typeof check.accepted.verdict?.id === "string" ? check.accepted.verdict.id : null,
+    };
+  }
+
+  const merged = resolved.forge.merge(doc.number, { sha: head, method: input.method });
+  if (!merged.ok) return merged;
+  // Post-verify: the forge must report the PR merged.
+  let state = "open";
+  for (const delay of [0, ...VERIFY_DELAYS_MS]) {
+    if (delay) await sleep(delay);
+    const after = resolved.forge.prStatus(doc.number);
+    if (after.ok) state = after.data.state;
+    if (state === "merged") break;
+  }
+  if (state !== "merged")
+    return {
+      ok: false,
+      code: "failed",
+      error: `merge_unverified: the forge accepted the merge of ${label} but still reports it ${state}`,
+      unblock: `workit verify-delivery merged --pr ${doc.number}`,
+    };
+
+  let deletedBranch: MergeOutcome["deletedBranch"] = false;
+  if (input.deleteBranch) {
+    const deleted = deleteRemoteBranch(cwd, resolved.remote, branch, head);
+    // The forge may delete merged branches itself; gone is deleted.
+    const gone = !deleted.ok && remoteRefTip(cwd, resolved.remote, `refs/heads/${branch}`);
+    deletedBranch =
+      deleted.ok || (gone && gone.ok && gone.sha === null) ? true : { error: deleted.error };
+  }
+  const row = appendObserved(cwd, {
+    type: "pr.merged",
+    actor: input.actor,
+    branch,
+    head,
+    pr: doc.number,
+    base: doc.base,
+    mergeSha: merged.data.mergeSha,
+    method: input.method,
+    verdictId: verdict.verdictId,
+    grant: grant.source,
+  });
+  return {
+    ok: true,
+    data: {
+      number: doc.number,
+      url: doc.url,
+      branch,
+      base: doc.base,
+      head,
+      method: input.method,
+      mergeSha: merged.data.mergeSha,
+      verdict,
+      grant: { source: grant.source },
+      deletedBranch,
+      recorded: row.ok ? { id: String(row.value.id) } : { error: row.error },
+    },
+  };
+}

package/src/forge/redact.ts

@@ -0,0 +1,191 @@
+// Redaction and bounding for text that comes back from a forge: CI logs,
+// review comments, CLI stderr. All of it is untrusted data that an agent will
+// read, so secrets are masked and the size is capped before it leaves core.
+
+const R = "[REDACTED]";
+
+// Token formats that are secrets wherever they appear.
+const TOKEN_PATTERNS: readonly RegExp[] = [
+  // GitHub tokens (classic, fine-grained, app, OAuth, refresh).
+  /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/gu,
+  // GitLab tokens: glpat-, glrt-, gldt-, glcbt-, glptt-, glft-, gloas-, …
+  /\bgl[a-z]{1,8}-[A-Za-z0-9_-]{16,}/gu,
+  /\bnpm_[A-Za-z0-9]{30,}/gu,
+  /\bxox[abposr]-[A-Za-z0-9-]{10,}/gu,
+  /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/gu,
+  /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}/gu,
+  /\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}/gu,
+  /\bAIza[0-9A-Za-z_-]{35}/gu,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/gu,
+];
+
+// Slack/Discord webhooks: the path is the credential.
+const WEBHOOK =
+  /\b(https?:\/\/(?:hooks\.slack\.com\/(?:services|workflows|triggers)|discord(?:app)?\.com\/api\/webhooks))\/[^\s"'<>]+/giu;
+
+// Userinfo in any URL (`https://user:pw@`, `postgres://a:b:c@`, `https://tok@`).
+const URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/giu;
+
+// `curl -u user:pass`, `--user user:pass`.
+const CURL_USER = /(\s(?:-u|--user)(?:\s+|=))(["']?)[^\s"':]+:[^\s"']+\2/gu;
+
+// Secret-ish keys in env dumps, YAML, JSON, headers and connection strings:
+// DB_PASSWORD=…, "access_token": "…", X-Api-Key: …, PRIVATE-TOKEN: …,
+// AccountKey=…; an optional auth scheme (Basic/Bearer) is kept.
+const KEY = String.raw`[A-Za-z0-9_.-]*?(?:token|secret|password|passwd|pwd|api[_-]?key|access[_-]?key|account[_-]?key|private[_-]?key|client[_-]?secret|credentials?|authorization|cookie|signature)[A-Za-z0-9_.-]*`;
+const ASSIGNMENT = new RegExp(
+  String.raw`(?<![A-Za-z0-9])(["']?${KEY}["']?\s*[:=]\s*["']?)((?:bearer|basic|token|digest)\s+)?([^\s"',;&]+)`,
+  "giu",
+);
+
+const BEARER = /\b(bearer\s+)[A-Za-z0-9._~+/-]{12,}=*/giu;
+
+// A quoted value may contain spaces: password: "correct horse battery".
+const QUOTED_ASSIGNMENT = new RegExp(
+  String.raw`(?<![A-Za-z0-9])(["']?${KEY}["']?\s*[:=]\s*)(["'])([^"'\n]*[^\s"'][^"'\n]*)\2`,
+  "giu",
+);
+
+// ~/.netrc: `machine h login u password p` (also split across lines).
+const NETRC = /\b((?:machine|login)\s+\S+\s+(?:login\s+\S+\s+)?password\s+)\S+/giu;
+
+// Secrets passed as CLI flags: sshpass -p X, mysql -pX / -p X.
+const FLAG_SECRETS: readonly RegExp[] = [
+  /\b(sshpass\s+-p\s*)\S+/gu,
+  /\b(mysql(?:dump|admin|import|show)?\b[^\n]*?\s-p)(?!\s|$)\S+/gu,
+];
+
+// Signed-URL and query-string credentials (Azure SAS `sig=`, `token=`, …).
+const QUERY_SECRET =
+  /([?&;](?:sig|signature|token|access_token|api_key|apikey|key|password|secret|client_secret|X-Amz-Signature|X-Goog-Signature)=)[^&\s#"']+/giu;
+
+// A key block from BEGIN to END, or to the end of the text when truncated.
+const PRIVATE_KEY =
+  /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----|$)/gu;
+
+// Long base64 runs: redacted when they decode to a credential, or sit on a
+// line that decodes base64 (`echo … | base64 -d`).
+const BASE64 = /[A-Za-z0-9+/]{32,}={0,2}/gu;
+
+const ANSI = new RegExp(String.raw`\u001b\[[0-9;?]*[ -/]*[@-~]|\u001b\][^\u0007]*\u0007`, "gu");
+
+export const stripAnsi = (value: string): string => value.replace(ANSI, "");
+
+const decodesToSecret = (blob: string): boolean => {
+  if (/^[0-9a-f]+$/iu.test(blob)) return false; // hex: commit/tree ids
+  let decoded: string;
+  try {
+    decoded = Buffer.from(blob, "base64").toString("utf8");
+  } catch {
+    return false;
+  }
+  if (!/^[\x20-\x7e\s]+$/u.test(decoded)) return false;
+  return (
+    TOKEN_PATTERNS.some((pattern) => new RegExp(pattern.source, "u").test(decoded)) ||
+    /^[^\s:]{1,64}:[^\s]{6,}$/u.test(decoded.trim())
+  );
+};
+
+/** Mask secrets and strip terminal escapes. Works on whole (multi-line) text. */
+export function redactText(value: string): string {
+  let out = stripAnsi(value).replace(PRIVATE_KEY, "[REDACTED PRIVATE KEY]");
+  out = out.replace(WEBHOOK, `$1/${R}`);
+  out = out.replace(URL_USERINFO, `$1${R}@`);
+  for (const pattern of TOKEN_PATTERNS) out = out.replace(pattern, R);
+  out = out.replace(CURL_USER, `$1$2${R}$2`);
+  out = out.replace(BEARER, `$1${R}`);
+  out = out.replace(QUOTED_ASSIGNMENT, (match, lead: string, quote: string, secret: string) =>
+    secret.startsWith(R) ? match : `${lead}${quote}${R}${quote}`,
+  );
+  out = out.replace(NETRC, `$1${R}`);
+  for (const pattern of FLAG_SECRETS) out = out.replace(pattern, `$1${R}`);
+  out = out.replace(QUERY_SECRET, `$1${R}`);
+  out = out.replace(
+    ASSIGNMENT,
+    (match, lead: string, scheme: string | undefined, secret: string) =>
+      secret.startsWith(R) ? match : `${lead}${scheme ?? ""}${R}`,
+  );
+  return out
+    .split("\n")
+    .map((line) =>
+      line.replace(BASE64, (blob) =>
+        /\bbase64\b/iu.test(line) || decodesToSecret(blob) ? R : blob,
+      ),
+    )
+    .join("\n");
+}
+
+// GitHub Actions prefixes every log line with an ISO timestamp; GitLab traces
+// carry section markers and a leading timestamp/stream tag in newer runners.
+const LINE_NOISE = /^(?:\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\s?)?(?:\d{2}[A-Z]\s)?/u;
+const GITLAB_SECTION = /section_(?:start|end):\d+:[A-Za-z0-9_.-]+(?:\[[^\]]*\])?\r?/gu;
+
+// Where the failure ends: everything after is runner cleanup.
+const FAILURE_END = [/##\[error\]Process completed with exit code/u, /^ERROR: Job failed\b/u];
+
+const MAX_LINE = 400;
+
+// The first line that looks like the actual failure: a strong marker (a
+// test-runner failure, an assertion, a thrown error) wins over a weak one
+// (any "failed"/"ERROR" mention, which passing tests also print).
+const STRONG_ERROR =
+  /^\s*(?:\(fail\)|FAIL\b|✗|✕|×|error(?:\[[A-Z0-9]+\])?:|[A-Za-z]*Error\b:|AssertionError|Traceback|panic:|Exception\b)/u;
+const WEAK_ERROR = /\berror\b[:[]|\bERROR\b|\bFAIL(?:ED)?\b|\bfailed\b|\bassert/u;
+// Passing test lines and summaries mention failure words without failing.
+const NOT_FIRST_ERROR =
+  /^\s*(?:\(pass\)|\(skip\)|\(todo\)|✓|✔|ok\b|PASS\b)|^\s*\d+ fail\b|##\[error\]Process completed|^\s*0 (?:errors?|fail)/u;
+
+/** Lines of context kept before the first error. */
+const LEAD = 3;
+
+/**
+ * A bounded, redacted view of a CI log: at most `lines` lines. Runner
+ * cleanup after the failure marker is dropped. When the first error sits
+ * before the final window, the view is the region around that first error,
+ * a `…` gap, then the end of the log (where the summary and exit code are).
+ */
+export function logTail(text: string, lines: number): string[] {
+  if (lines <= 0) return [];
+  const cleaned = text
+    .replace(GITLAB_SECTION, "")
+    .split(/\r?\n/u)
+    // A bare \r rewrites the line in a terminal (progress bars): keep what
+    // was finally shown.
+    .map(
+      (raw) =>
+        stripAnsi(raw)
+          .split("\r")
+          .findLast((part) => part.trim()) ?? "",
+    )
+    .map((raw) => raw.replace(LINE_NOISE, ""));
+  // Redact the whole text so a secret spanning lines (a private key) goes.
+  const all = redactText(cleaned.join("\n")).split("\n");
+  let end = all.length;
+  for (let index = all.length - 1; index >= 0; index -= 1)
+    if (FAILURE_END.some((pattern) => pattern.test(all[index]))) {
+      end = index + 1;
+      break;
+    }
+  const kept = all.slice(0, end);
+  while (kept.length > 0 && !kept[kept.length - 1].trim()) kept.pop();
+  const cap = (value: string) => (value.length > MAX_LINE ? `${value.slice(0, MAX_LINE)}…` : value);
+  const tailStart = Math.max(0, kept.length - lines);
+  const find = (pattern: RegExp) =>
+    kept.findIndex((value) => pattern.test(value) && !NOT_FIRST_ERROR.test(value));
+  const strong = find(STRONG_ERROR);
+  const first = strong >= 0 ? strong : find(WEAK_ERROR);
+  if (first < 0 || first >= tailStart || lines < 8) return kept.slice(tailStart).map(cap);
+  const headCount = Math.ceil((lines - 1) * (2 / 3));
+  const from = Math.max(0, first - LEAD);
+  const head = kept.slice(from, from + headCount);
+  const tailCount = lines - 1 - head.length;
+  const tailFrom = Math.max(from + head.length, kept.length - tailCount);
+  const tail = kept.slice(tailFrom);
+  return [...head, ...(tailFrom > from + head.length ? ["…"] : []), ...tail].map(cap);
+}
+
+/** One-line, redacted, length-capped text (review comment bodies). */
+export function shortBody(value: string, max = 300): string {
+  const flat = redactText(value).replace(/\s+/gu, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}