@intentius/chant 0.124.13 → 0.124.14

package/dist/op/activities/reconcile.js

@@ -0,0 +1,997 @@
+import { exec } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { ForgeApiError, forgejoForge, githubForge } from "../../pr-forge.js";
+import { ghHostEnv } from "./gh-host.js";
+import { restPullRequestForge } from "./forge-pull-request.js";
+const execAsync = promisify(exec);
+/** Default branch name for a reconcile PR. Deterministic — no timestamp. */
+export function reconcileBranchName(env) {
+    const safe = env.replace(/[^a-zA-Z0-9._-]+/g, "-");
+    return `chant/reconcile-${safe}`;
+}
+/**
+ * Build the markdown body summarizing which change-set entries triggered the
+ * reconcile. Pure — used as the PR/issue body and returned in `report` mode.
+ */
+export function reconcileSummary(env, entries) {
+    const lines = [
+        `Reconcile from live environment \`${env}\`.`,
+        "",
+        "This PR regenerates chant TypeScript from live state to close the gap between the cloud and source. It was triggered by the following change-set entries:",
+        "",
+        "| Entry | Action | Type |",
+        "|---|---|---|",
+    ];
+    for (const e of entries) {
+        lines.push(`| ${e.name} | ${e.action} | ${e.type ?? ""} |`);
+    }
+    if (entries.length === 0) {
+        lines.push("| _(none)_ | | |");
+    }
+    lines.push("");
+    lines.push("Review the diff before merging — live import may surface values that need redaction.");
+    return lines.join("\n");
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * The hidden marker that makes a `comment`-mode finding findable across
+ * re-runs: written as the comment's first line, matched with `startswith` on
+ * the next run. Keyed on `env` (slugified the same way {@link
+ * reconcileBranchName} slugifies it, which also keeps the value free of the
+ * quotes and backslashes it is interpolated next to), so two Ops over two
+ * environments own two comments and each updates in place.
+ */
+export function commentMarker(env) {
+    return `<!-- chant-reconcile:${markerSlug(env)} -->`;
+}
+/**
+ * The hidden marker that makes an `issue`-mode finding findable across re-runs
+ * (#2292, #2297): written as the issue description's first line, matched on
+ * the next run by a `startswith` check (GitHub/Forgejo) or a server-side
+ * `search` plus the same check (GitLab). The same recipe {@link commentMarker}
+ * names for the `comment` mode's note, kept as its own function (rather than
+ * reused) because the two modes write to different resources and a caller may
+ * run both against the same `env`.
+ *
+ * Keyed on the owning Op *and* the env, not the env alone (#2319). An
+ * env-keyed marker was not unique, and once #2311 made this mode edit in place
+ * that stopped being merely untidy: `postOrUpdateGithubIssue` PATCHes both the
+ * title and the body of whatever it matches, so two Ops resolving to one
+ * marker rewrite each other's report on every run and the issue alternates
+ * between two unrelated findings. Two in-tree pairings hit it — a stock
+ * `TerraformWatchOp` and a `live: true` one over the same root (both pass the
+ * root as `env`), and a `ReconcileOp` for a chant environment whose name
+ * matches some terraform root — and both are ordinary configurations, not
+ * abuse. The Op name is the identifier closest to unique that this activity
+ * can be handed: it names the Op's output directory and is what `chant run`
+ * takes, so two Ops in a project do not share a raw name.
+ * `lexicons/github`'s gate notice reached the same conclusion first, keying
+ * its own sticky marker on `$CHANT_OP` alone.
+ *
+ * Both halves are slugified the same way {@link reconcileBranchName} slugifies
+ * an env, which also keeps the value free of the quotes and backslashes it is
+ * interpolated next to and of anything URL-encoding should have to escape out
+ * of. `/` cannot survive that slugify, so it separates the two halves
+ * unambiguously: the marker parses back to exactly one `op` slug and one `env`
+ * slug.
+ *
+ * What that leaves, and what is accepted rather than solved (#2319 pre-merge
+ * review): the slug is not injective. {@link markerSlug} collapses every run
+ * of characters outside `[A-Za-z0-9._-]` to a single `-`, so `"app watch"` and
+ * `"app:watch"` share a slug, and so do `"café"` and `"caf€"`. Two Ops named
+ * that way in one project over one env would still collide. Nothing in this
+ * repository constrains an Op name's character set today, so this cannot be
+ * closed here — it wants a charset rule on `OpConfig.name` (which would also
+ * settle the output directory and the branch name, both of which slugify the
+ * same way and have the same aliasing). Until then the residual is: distinct
+ * raw names, distinct markers, unless the names differ only in characters the
+ * slug does not keep.
+ */
+export function issueMarker(op, env) {
+    return `<!-- chant-reconcile-issue:${markerSlug(op)}/${markerSlug(env)} -->`;
+}
+/**
+ * The slugify every marker shares: everything outside `[A-Za-z0-9._-]`
+ * collapses to `-`. Exported for the behaviour finding's own marker
+ * (`./predict-behaviour.ts`), so a third marker cannot slugify differently
+ * from the two here.
+ */
+export function markerSlug(s) {
+    return s.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+/**
+ * What any mode says about a supplied `marker` it cannot use safely (#2319
+ * pre-merge review).
+ *
+ * The marker is interpolated raw into the `--jq` filter that finds this Op's
+ * own comment or issue, inside a jq string literal: `startswith("<marker>")`.
+ * Only the whole filter is shell-quoted, so a `"` or a `\` in the marker
+ * closes or escapes past that literal — at best a jq syntax error, at worst a
+ * filter that matches something other than what the caller wrote. A control
+ * character does the same to the jq program's own line structure.
+ *
+ * Markers this activity builds itself cannot contain any of the three:
+ * {@link markerSlug} keeps them to `[A-Za-z0-9._-]` plus the fixed `<!-- … -->`
+ * frame. This checks the one that comes in from outside, and refuses rather
+ * than escaping, because a marker is an identity a caller has to be able to
+ * predict — silently rewriting it would move the issue this run owns.
+ */
+export function unsafeMarkerMessage(marker) {
+    return (`reconcilePr was given the marker ${JSON.stringify(marker)}, which it cannot use. The marker goes into ` +
+        'the `--jq` filter that finds this Op\'s own comment or issue, as `startswith("<marker>")`, so a double ' +
+        "quote, a backslash or a control character in it either breaks that filter or changes what it matches. " +
+        "Markers this activity builds itself are slugified to letters, digits, dot, underscore and hyphen and " +
+        "cannot contain any of the three. Keep a supplied marker to printable text without `\"` or `\\`, or drop " +
+        "`marker` and pass `op` instead.");
+}
+/**
+ * The caller's `marker` as this activity will actually use it, or `undefined`
+ * when the caller supplied nothing usable (#2319 pre-merge review).
+ *
+ * Blank is not a marker. `""` and `"   "` used to satisfy the `issue`-mode
+ * identity check — `args.marker === undefined` is false for both, and `??`
+ * only falls through on nullish — and then built `startswith("")`, which is
+ * true of every issue body in the repository. So the step took whichever OPEN
+ * non-pull-request issue the forge listed first, very possibly a human's, and
+ * PATCHed its title and body. That is the precise failure #2319 exists to
+ * close, reachable through the escape hatch #2319 added, which is why the
+ * check lives on the field rather than in one mode's branch.
+ *
+ * Trimming rather than only rejecting: a marker with a trailing space is
+ * written and matched consistently either way, and normalizing it here means
+ * one definition of "blank" for both modes.
+ */
+export function suppliedMarker(marker) {
+    const trimmed = marker?.trim();
+    if (!trimmed)
+        return undefined;
+    if (/["\\]|[\u0000-\u001f\u007f]/.test(trimmed))
+        throw new Error(unsafeMarkerMessage(trimmed));
+    return trimmed;
+}
+/**
+ * What an `issue`-mode step says when it was given no identity to key its
+ * marker on (#2319).
+ *
+ * A refusal rather than a fall back to the pre-#2319 env-only marker, because
+ * the fallback is the bug: it is silent, it looks like it worked, and what it
+ * costs is the *other* Op's report, which nobody is watching the log of. The
+ * step that has to change is the one being refused, and the message names the
+ * two ways to change it.
+ */
+export function noIssueIdentityMessage(env) {
+    return ('reconcilePr mode "issue" edits the one OPEN issue carrying this Op\'s hidden marker in place, so the ' +
+        `marker has to name the Op. This step supplies env "${env}" and no identity, and an env alone is not ` +
+        "unique: two Ops over one env — a stock terraform drift watch and a live one over the same root, or a " +
+        "terraform root and a chant environment that happen to share a name — resolve to the same marker, and " +
+        "each run then rewrites the other's issue title and body. Pass `op` with the Op's own name (every " +
+        "composite in tree does), or pass an explicit `marker` you keep unique yourself.");
+}
+/** What a `comment`-mode step says when the run it is in has no pull request and no merge request. */
+export function noPullRequestContextMessage() {
+    return ('reconcilePr mode "comment" posts the finding on the pull request or merge request that triggered the ' +
+        "run, and this run has none. On GitHub Actions it needs GITHUB_REPOSITORY plus a pull request number, " +
+        "read from the event payload at GITHUB_EVENT_PATH (`.number` / `.pull_request.number`) or from " +
+        "GITHUB_REF (`refs/pull/<n>/merge`), which a pull_request event sets and nothing else does. On GitLab " +
+        "CI it needs CI_MERGE_REQUEST_IID plus the project (CI_MERGE_REQUEST_PROJECT_ID or CI_PROJECT_ID) and " +
+        "the API base (CI_API_V4_URL, or CI_SERVER_URL to derive it), which a merge_request_event pipeline " +
+        "sets and nothing else does. Trigger this Op from a pull_request or merge_request pipeline, or give " +
+        'it findingMode "issue" or "report".');
+}
+/**
+ * Read the pull request number out of a parsed webhook event payload. Pure.
+ * A `pull_request` event carries it top-level as `number` and again under
+ * `pull_request.number`; both are accepted, neither is invented.
+ */
+function prNumberFromPayload(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return undefined;
+    const p = payload;
+    if (typeof p.number === "number")
+        return p.number;
+    if (typeof p.pull_request?.number === "number")
+        return p.pull_request.number;
+    return undefined;
+}
+/**
+ * Derive the triggering pull request from CI environment variables plus the
+ * already-parsed event payload. Pure — exported for testing; the IO (reading
+ * `GITHUB_EVENT_PATH`) is {@link resolvePullRequestContext}'s.
+ *
+ * Returns undefined rather than throwing, so the caller owns the message.
+ */
+export function pullRequestContextFrom(env, eventPayload) {
+    const repo = env.GITHUB_REPOSITORY;
+    if (!repo)
+        return undefined;
+    const fromRef = /^refs\/pull\/(\d+)\//.exec(env.GITHUB_REF ?? "")?.[1];
+    const number = prNumberFromPayload(eventPayload) ?? (fromRef ? Number(fromRef) : undefined);
+    if (number === undefined || !Number.isInteger(number) || number <= 0)
+        return undefined;
+    return { repo, number };
+}
+/**
+ * Resolve the triggering pull request, reading and parsing the event payload
+ * `GITHUB_EVENT_PATH` names. Throws {@link noPullRequestContextMessage} when
+ * the run has no pull request, which is the whole point: a `comment` mode that
+ * quietly fell back to an issue would post the finding somewhere nobody asked
+ * for it.
+ */
+export async function resolvePullRequestContext(env = process.env) {
+    let payload;
+    const eventPath = env.GITHUB_EVENT_PATH;
+    if (eventPath) {
+        try {
+            payload = JSON.parse(await readFile(eventPath, "utf8"));
+        }
+        catch {
+            // An unreadable or malformed payload is not fatal on its own: GITHUB_REF
+            // may still name the pull request. If it does not, the error below says so.
+            payload = undefined;
+        }
+    }
+    const ctx = pullRequestContextFrom(env, payload);
+    if (!ctx)
+        throw new Error(noPullRequestContextMessage());
+    return ctx;
+}
+/**
+ * The REST base a GitHub-shaped `gh api` call should target, read the same
+ * way the runner itself reads it (chant #2291). `GITHUB_API_URL` is a default
+ * environment variable every GitHub Actions *and* Forgejo Actions job carries
+ * — `https://api.github.com` on github.com, `<host>/api/v3` on GitHub
+ * Enterprise Server, and `<host>/api/v1` on Forgejo, which already advertises
+ * it correctly (confirmed on a real Forgejo 12.0.4+gitea-1.22.0 instance
+ * during INTENTIUS/choudoufu#1027: `$GITHUB_API_URL` read
+ * `http://forgejo:3000/api/v1` inside the job).
+ *
+ * Building the full URL from this rather than handing `gh api` a bare
+ * relative path (`repos/…`) is the fix itself: `gh` resolves a relative path
+ * by guessing a host-specific prefix of its own — `api.<host>` for
+ * `github.com`, `<host>/api/v3` for anything else — and that guess is `/api/v3`
+ * for a Forgejo host too, which Forgejo answers 404 for both GET and POST.
+ * Handed a full URL, `gh api` uses it verbatim and skips the guess entirely,
+ * which is what let the same `gh` binary reach Forgejo's `/api/v1` in the
+ * same session, over plain HTTP and over TLS. No Forgejo-specific branch is
+ * needed: every host in play (github.com, GHES, Forgejo) sets
+ * `GITHUB_API_URL` to the base its own `/repos/...` paths actually live
+ * under, so building the URL from it is correct everywhere `gh` already ran,
+ * not only on Forgejo.
+ */
+export function githubApiBaseFrom(env) {
+    return env.GITHUB_API_URL?.trim().replace(/\/+$/, "") || "https://api.github.com";
+}
+/**
+ * Resolve the token the `comment` and `issue` modes post with on GitHub and
+ * Forgejo, most specific first (chant #2291). The generated workflow sets
+ * `GH_TOKEN` and `GITHUB_TOKEN` to `${{ github.token }}` for every
+ * non-`report` finding mode — on
+ * Forgejo the same way as on GitHub, and the real-instance read confirmed
+ * `github.token` is populated there and good for a 200 read and a 201 write,
+ * authored as `forgejo-actions`. So the common case needs nothing set beyond
+ * what the generator already emits.
+ *
+ * `CHANT_FORGEJO_TOKEN` is checked first for the case that ambient token
+ * cannot cover: a run posting to a Forgejo instance other than the one the
+ * job executes on, where `github.token`'s scope stops at its own instance.
+ * A run with none of the three is refused by name before any call, in place
+ * of the forge's own opaque 401.
+ */
+export function commentTokenFrom(env) {
+    for (const source of ["CHANT_FORGEJO_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]) {
+        const value = env[source]?.trim();
+        if (value)
+            return { value, source };
+    }
+    return undefined;
+}
+/**
+ * The environment a `gh api` call carries {@link commentTokenFrom}'s resolved
+ * credential in (chant #2333).
+ *
+ * `GH_TOKEN` alone is not enough, and that is `gh`'s documented behavior
+ * rather than a bug in it. `gh` picks the token per *request host*:
+ * `GH_TOKEN`/`GITHUB_TOKEN` are scoped to github.com and `ghe.com`
+ * subdomains, and every other host — a self-hosted Forgejo, a self-hosted
+ * GitHub Enterprise Server — reads `GH_ENTERPRISE_TOKEN`/
+ * `GITHUB_ENTERPRISE_TOKEN` instead (`gh help environment`). #2291 fixed the
+ * *URL* half of reaching a non-github.com host and left this half untouched,
+ * so 0.62.0 and 0.63.0 both shipped a `comment` mode that posts to Forgejo
+ * with no `Authorization` header at all.
+ *
+ * Confirmed against a real Forgejo 12.0.4+gitea-1.22.0 instance under #2333,
+ * from a shell whose `GH_CONFIG_DIR` held no `gh auth login` — the condition
+ * a fresh Actions checkout starts from, and the one #2304's verification did
+ * not reproduce. Driving this function's own POST with `GH_DEBUG=api`:
+ * `GH_TOKEN` alone sent no `Authorization` header and got HTTP 401
+ * `{"message":"token is required"}`, `GH_TOKEN` with `GITHUB_TOKEN` beside it
+ * got the same 401, and `GH_TOKEN` with `GH_HOST` beside it got the same 401
+ * again. `GH_ENTERPRISE_TOKEN` sent `Authorization: token …` and got HTTP 201.
+ *
+ * So the fix is one variable, set to the same value: whichever class `gh`
+ * decides the host falls into, the credential it finds there is the one
+ * {@link commentTokenFrom} resolved. That is why this does not branch on the
+ * forge, and why it needs no host detection of chant's own — the thing that
+ * broke was `gh`'s host classification, and setting both classes to one value
+ * is what stops chant depending on it.
+ *
+ * ## Why `GH_HOST` is deliberately not set
+ *
+ * #2333 proposed `GH_ENTERPRISE_TOKEN` *plus* a `GH_HOST` derived from
+ * `GITHUB_API_URL`, on the reading that the pair was needed. It is not: the
+ * live instance took `GH_ENTERPRISE_TOKEN` on its own, with no `GH_HOST`
+ * anywhere in the environment, because {@link githubApiBaseFrom} already
+ * hands `gh api` a full URL and `gh` reads the host off that URL rather than
+ * off its default. `GH_HOST` sets the *default* host for calls that name no
+ * host — which is what `gh issue create`'s ambient fallback below relies on —
+ * so setting it would buy nothing here and put a variable into the
+ * environment of calls that do not want one.
+ *
+ * ## Why github.com is unchanged
+ *
+ * Both variables carry the same value, so the question is only which one
+ * `gh` reads, and github.com reads `GH_TOKEN`. Probed against the real
+ * api.github.com the same way: a valid `GH_TOKEN` with a deliberately
+ * garbage `GH_ENTERPRISE_TOKEN` beside it succeeded, and a garbage `GH_TOKEN`
+ * with a valid `GH_ENTERPRISE_TOKEN` beside it failed `Bad credentials`.
+ * `GH_TOKEN` wins on github.com whatever the enterprise variable holds, so
+ * the header a github.com call sends is byte-identical to the one it sent
+ * before this change.
+ *
+ * A *self-hosted* GHES host is in the same class as Forgejo and was equally
+ * broken — same `gh` code path, same missing header — so it is fixed by the
+ * same variable rather than merely preserved. That was inferred from `gh`'s
+ * documented scoping in #2332 and is not exercised here: no GHES instance was
+ * available to test against.
+ */
+export function ghCredentialEnv(base, token) {
+    return { ...base, GH_TOKEN: token.value, GH_ENTERPRISE_TOKEN: token.value };
+}
+/** What a `comment`-mode step says on a pull request it has no credential for. */
+export function noCommentTokenMessage(repo, number) {
+    return (`reconcilePr mode "comment" has pull request ${repo}#${number} to post its finding on and no token to ` +
+        "post it with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions " +
+        "or Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
+        "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ.");
+}
+/** What an `issue`-mode step says on a repository it has no credential for (#2320). */
+export function noIssueTokenMessage(repo) {
+    return (`reconcilePr mode "issue" has repository ${repo} to open or edit its finding in and no token to do it ` +
+        "with. GH_TOKEN or GITHUB_TOKEN, set from github.token, already covers this on a GitHub Actions or " +
+        "Forgejo Actions run — set CHANT_FORGEJO_TOKEN to post against a different instance than the one the " +
+        "job runs on. CHANT_FORGEJO_TOKEN is read first where the two must differ.");
+}
+/**
+ * The GitHub or Forgejo client a `comment` or `issue` finding posts through
+ * (#3757): `../../pr-forge.ts`, the one the pull-request loop already uses,
+ * over `fetch`. These two modes used to shell to `gh`, which needed `gh` on
+ * the runner and needed it to attach a credential to a host it did not
+ * recognise (#2333). The token is the one {@link commentTokenFrom} resolved
+ * and the base is {@link githubApiBaseFrom}'s, so nothing about what a step
+ * sets has changed.
+ *
+ * The two forges share every call these modes make and differ on two things
+ * the client needs to know: the page parameter (`per_page` against `limit`)
+ * and the authorization scheme. A Forgejo run is told apart the way
+ * `../gate-resume.ts` tells it apart, by `FORGEJO_ACTIONS` or
+ * `GITEA_ACTIONS`, and also by an API base ending in `/api/v1`, which is how
+ * a step posting to some other Forgejo instance (`CHANT_FORGEJO_TOKEN`) names
+ * it. GitHub serves `/api/v3` or `api.github.com`, never `/api/v1`.
+ */
+export function githubShapedForgeFrom(env, repo, token, signal) {
+    const apiBase = githubApiBaseFrom(env);
+    const forgejo = env.FORGEJO_ACTIONS === "true" || env.GITEA_ACTIONS === "true" || /\/api\/v1$/.test(apiBase);
+    // Read at call time, so a test that stubs the global sees its stub.
+    const fetchImpl = (url, init) => globalThis.fetch(url, { ...init, ...(signal ? { signal } : {}) });
+    const opts = { apiBase, repo, token: token.value, fetch: fetchImpl };
+    if (!forgejo)
+        return githubForge(opts);
+    let host;
+    try {
+        host = new URL(apiBase).host;
+    }
+    catch {
+        host = apiBase;
+    }
+    return forgejoForge({ ...opts, host });
+}
+/** A forge's refusal, carrying which variable the token came from, the way the GitLab half's errors do. */
+async function withTokenSource(token, call) {
+    try {
+        return await call();
+    }
+    catch (err) {
+        if (err instanceof ForgeApiError)
+            throw new Error(`${err.message} (token from ${token.source}).`);
+        throw err;
+    }
+}
+/**
+ * Post `body` as one comment on `ctx`'s pull request, or edit the comment this
+ * Op already owns there: the comment whose body starts with `marker`, found
+ * by paging every comment on the pull request, PATCHed when there is one and
+ * POSTed when there is not. The same note recipe `PrPlanReport` and the
+ * pull-request loop use. A missing token is refused by name before any call.
+ */
+async function postOrUpdateComment(ctx, marker, body, signal) {
+    const token = commentTokenFrom(process.env);
+    if (!token)
+        throw new Error(noCommentTokenMessage(ctx.repo, ctx.number));
+    const forge = githubShapedForgeFrom(process.env, ctx.repo, token, signal);
+    return withTokenSource(token, () => forge.upsertNote(ctx.number, marker, `${marker}\n\n${body}`));
+}
+/**
+ * Open `title`/`body` as one GitHub-shaped issue in `repo`, or edit the issue
+ * this caller already owns there (#2297), over `gh api`: find by marker,
+ * PATCH when found, POST when not, so a nightly finding carries one issue
+ * holding the current state instead of stacking a new one every run.
+ * `lexiconUpgrade`'s per-lexicon upgrade-status issue uses it. `reconcilePr`'s
+ * `issue` mode used it until #3757 and now keeps the same issue by the same
+ * recipe through the forge client's `upsertIssue` (`../../pr-forge.ts`), so
+ * the reasoning below covers both.
+ *
+ * Every call targets a full URL built from {@link githubApiBaseFrom} (#2291),
+ * so this reaches GitHub Enterprise Server and Forgejo the same way it
+ * reaches github.com.
+ *
+ * The credential is resolved and forwarded the same way too (chant #2320),
+ * through {@link commentTokenFrom} and out through {@link ghCredentialEnv} on
+ * every call. It did not used to be: `reconcilePr` handed this `(cmd) => execAsync(cmd, {
+ * signal })` with no `env` at all, so `CHANT_FORGEJO_TOKEN` never reached
+ * `gh` and the one case that variable exists for — posting to a Forgejo
+ * instance other than the one the job runs on, where `github.token`'s scope
+ * stops at its own instance — failed with a 401 or a 404 that named nothing.
+ * With no token at all the operator got `gh`'s own error rather than chant's.
+ * The refusal here is {@link noIssueTokenMessage}, not the `comment` mode's
+ * {@link noCommentTokenMessage}: same resolution order, same advice, but that
+ * message names a pull request this mode does not have, and this function is
+ * shared with `lexiconUpgrade`, which is not `reconcilePr` at all. The same
+ * split GitLab already makes between `noGitlabNoteTokenMessage` and
+ * `noGitlabIssueTokenMessage`.
+ *
+ * ## Why plain pagination instead of GitHub's Search API
+ *
+ * GitHub offers real server-side full-text search — `gh issue list --search`
+ * and `GET /search/issues?q=...` both use it, and chant #2297 (the issue that
+ * asked for this) names both as candidates. Neither is used here, for three
+ * reasons found while building this:
+ *
+ * 1. **Consistency.** GitHub's search index is documented as eventually
+ *    consistent: an issue this function just wrote is not guaranteed to be
+ *    findable by search immediately afterward. That is exactly the
+ *    read-after-write the sticky recipe depends on — a false "not found"
+ *    means a duplicate issue, which is the bug this activity exists to fix.
+ * 2. **The marker itself.** The hidden marker is deliberately punctuation-
+ *    heavy (`<!-- chant-reconcile-issue:nightly/app -->`) so it renders
+ *    invisibly. GitHub's search tokenizer is not documented to preserve that
+ *    shape through `in:body` matching, and a wrong query would either miss the
+ *    marker (a duplicate, the same failure mode as above) or over-match and
+ *    still need the same client-side `startswith` check this function
+ *    already does — at which point the search bought nothing but risk.
+ * 3. **Forgejo.** `gh issue list --search` and `/search/issues` are both
+ *    absent from Forgejo's API — checked against a live Forgejo instance's
+ *    own OpenAPI spec while building this: no `/search/issues`, no
+ *    `/repos/issues/search` path anywhere in it (Forgejo's own issues-list
+ *    endpoint does carry a real `q` search parameter, but that is a
+ *    different endpoint shape than GitHub's, which would mean forking this
+ *    function by forge — exactly what the `comment` path (#2291)
+ *    deliberately does not do). Chant #2315 confirmed this against a live
+ *    call rather than only the spec: plain paginated `GET .../issues?state=
+ *    open` on a real Forgejo 12.0.4+gitea-1.22.0 instance interleaves pull
+ *    requests with issues exactly as GitHub's endpoint does, and the
+ *    `.pull_request == null` filter below excludes them correctly. The write
+ *    calls this function makes did not clear the same instance until chant
+ *    #2333 gave them a credential `gh` would apply to that host — see the
+ *    module doc's `issue` bullet and {@link ghCredentialEnv}.
+ *
+ * So this reuses the recipe `comment` mode already proved for PR
+ * comments: list, `--paginate`, filter with `--jq` by an exact `startswith`
+ * prefix match, which is correct no matter how many pages it takes. The cost
+ * is real — a repository with many thousands of issues pays for every page
+ * on every run — and is the accepted trade-off here; narrowing further with
+ * GitHub's `creator` filter was considered and left alone, because the
+ * identity a `GH_TOKEN` posts as cannot be assumed reliably across a
+ * generated workflow and a hand-run one, and a wrong `creator` is a false
+ * negative — a duplicate — not just a slower search.
+ *
+ * ## The close decision (#2297)
+ *
+ * This never closes the issue, in either branch, matching both GitLab paths
+ * (#2256, #2292) — neither of which closes anything either. The search is
+ * scoped to `state=open` rather than `state=all`, which makes that decision
+ * concrete rather than implicit: a human closing the issue by hand, once the
+ * drift it named is actually fixed, is what tells the *next* run to open a
+ * fresh issue for a fresh finding instead of silently rewriting the closed
+ * one back open-in-substance-but-not-in-state. The alternative — searching
+ * `state=all` and reopening on write — would need this activity to guess
+ * when a finding is "resolved" with no reliable signal for that (an empty
+ * change set this run says nothing about whether the *last* finding was
+ * fixed or just not evaluated), and would turn a deliberate human "done" into
+ * something the bot silently reverses on its next run.
+ *
+ * `.pull_request == null` is filtered out of the search because GitHub's
+ * issues-list endpoint also returns pull requests, which this function must
+ * never mistake for an issue it owns.
+ */
+export async function postOrUpdateGithubIssue(repo, marker, title, body, exec) {
+    const token = commentTokenFrom(process.env);
+    if (!token)
+        throw new Error(noIssueTokenMessage(repo));
+    const env = ghCredentialEnv(process.env, token);
+    const base = githubApiBaseFrom(process.env);
+    const listUrl = `${base}/repos/${repo}/issues?state=open`;
+    const jq = 'map(select((.pull_request == null) and ((.body // "") | startswith(' +
+        `"${marker}"))))` +
+        " | .[0].number // empty";
+    const { stdout: found } = await exec(`gh api ${shellQuote(listUrl)} --paginate --jq ${shellQuote(jq)}`, { env });
+    // `--paginate` prints one `--jq` result per page, so take the first line
+    // that is an id and ignore the empty ones the other pages produce.
+    const existing = found.split("\n").map((l) => l.trim()).find((l) => /^\d+$/.test(l));
+    const titleField = shellQuote(`title=${title}`);
+    const bodyField = shellQuote(`body=${marker}\n\n${body}`);
+    if (existing) {
+        const { stdout } = await exec(`gh api --method PATCH ${shellQuote(`${base}/repos/${repo}/issues/${existing}`)} ` +
+            `-f ${titleField} -f ${bodyField} --jq .html_url`, { env });
+        return stdout.trim();
+    }
+    const { stdout } = await exec(`gh api --method POST ${shellQuote(`${base}/repos/${repo}/issues`)} -f ${titleField} -f ${bodyField} --jq .html_url`, { env });
+    return stdout.trim();
+}
+/**
+ * Derive the triggering merge request from a GitLab job's CI variables. Pure
+ * — exported for testing, and the whole forge detection: nothing but a
+ * `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID`, so a run that
+ * has it is on GitLab and has a merge request, and a run that does not is
+ * neither.
+ *
+ * The project is the merge request's own (`CI_MERGE_REQUEST_PROJECT_ID`) in
+ * preference to the pipeline's (`CI_PROJECT_ID`): a merge request opened from
+ * a fork runs its pipeline in the fork, and the note belongs on the target
+ * project's merge request rather than on an iid that means something else in
+ * the fork.
+ *
+ * Returns undefined rather than throwing, so the caller owns the message.
+ */
+export function mergeRequestContextFrom(env) {
+    const rawIid = env.CI_MERGE_REQUEST_IID?.trim();
+    if (!rawIid)
+        return undefined;
+    const iid = Number(rawIid);
+    if (!Number.isInteger(iid) || iid <= 0)
+        return undefined;
+    const server = env.CI_SERVER_URL?.trim().replace(/\/+$/, "");
+    const api = env.CI_API_V4_URL?.trim().replace(/\/+$/, "") || (server ? `${server}/api/v4` : "");
+    if (!api)
+        return undefined;
+    const project = env.CI_MERGE_REQUEST_PROJECT_ID?.trim() ||
+        env.CI_PROJECT_ID?.trim() ||
+        env.CI_MERGE_REQUEST_PROJECT_PATH?.trim() ||
+        env.CI_PROJECT_PATH?.trim() ||
+        "";
+    if (!project)
+        return undefined;
+    const path = env.CI_MERGE_REQUEST_PROJECT_PATH?.trim() || env.CI_PROJECT_PATH?.trim();
+    const webUrl = env.CI_MERGE_REQUEST_PROJECT_URL?.trim() || env.CI_PROJECT_URL?.trim();
+    return {
+        api,
+        project,
+        iid,
+        ...(path ? { path } : {}),
+        ...(webUrl ? { webUrl } : {}),
+    };
+}
+/**
+ * Derive the GitLab project an `issue`-mode run is in, from the job's own CI
+ * variables. Pure — exported for testing, and the whole forge detection:
+ * `CI_PROJECT_ID` is set on every GitLab CI job, merge request or not, and
+ * nothing outside GitLab CI sets it — a GitHub Actions run never reaches this
+ * branch. Unlike {@link mergeRequestContextFrom}, no `CI_MERGE_REQUEST_IID`
+ * is required, since `issue` mode's whole point is a cron trigger that has
+ * none.
+ *
+ * Returns undefined rather than throwing, so the caller owns the fallback:
+ * a run with no GitLab signal falls through to `gh issue create`.
+ */
+export function gitlabProjectContextFrom(env) {
+    const project = env.CI_PROJECT_ID?.trim();
+    if (!project)
+        return undefined;
+    const server = env.CI_SERVER_URL?.trim().replace(/\/+$/, "");
+    const api = env.CI_API_V4_URL?.trim().replace(/\/+$/, "") || (server ? `${server}/api/v4` : "");
+    if (!api)
+        return undefined;
+    const path = env.CI_PROJECT_PATH?.trim();
+    const webUrl = env.CI_PROJECT_URL?.trim();
+    return {
+        api,
+        project,
+        ...(path ? { path } : {}),
+        ...(webUrl ? { webUrl } : {}),
+    };
+}
+/**
+ * Resolve the token a merge-request note is written with, most specific
+ * first. Pure — exported for testing.
+ *
+ * Two headers, not one, because GitLab reads two different credentials from
+ * two different headers: an access token goes in `PRIVATE-TOKEN`, and the
+ * pipeline's own ephemeral `CI_JOB_TOKEN` goes in `JOB-TOKEN`. Sending one in
+ * the other's header is a 401, not a fallback.
+ *
+ * The access token is preferred because it is the one that reliably works:
+ * `CI_JOB_TOKEN` reaches only the endpoints GitLab's job-token allowlist
+ * names, and the notes API is not among them on current GitLab, so a project
+ * that has not widened that allowlist needs a token with `api` scope. It is
+ * still accepted last rather than refused, so a project on an instance whose
+ * allowlist does cover notes needs no long-lived credential at all.
+ */
+export function gitlabNoteTokenFrom(env) {
+    for (const source of ["CHANT_GITLAB_TOKEN", "GITLAB_TOKEN"]) {
+        const value = env[source]?.trim();
+        if (value)
+            return { header: "PRIVATE-TOKEN", value, source };
+    }
+    const jobToken = env.CI_JOB_TOKEN?.trim();
+    if (jobToken)
+        return { header: "JOB-TOKEN", value: jobToken, source: "CI_JOB_TOKEN" };
+    return undefined;
+}
+/** What a `comment`-mode step says on a merge request it has no credential for. */
+export function noGitlabNoteTokenMessage(iid) {
+    return (`reconcilePr mode "comment" has merge request !${iid} to post its finding on and no token to post it ` +
+        "with. Set a GITLAB_TOKEN CI/CD variable (masked, scope: api) on the project — a project access token " +
+        "is enough — or, on an instance whose job-token allowlist covers the notes API, make CI_JOB_TOKEN " +
+        "available to the job. CHANT_GITLAB_TOKEN is read first where the two must differ.");
+}
+/** What an `issue`-mode step says on a GitLab project it has no credential for (#2292). */
+export function noGitlabIssueTokenMessage(project) {
+    return (`reconcilePr mode "issue" wants to open or update an issue on GitLab project ${project} and has no ` +
+        "token to do it with. Set a GITLAB_TOKEN CI/CD variable (masked, scope: api) on the project — a " +
+        "project access token is enough — or, on an instance whose job-token allowlist covers the issues API, " +
+        "make CI_JOB_TOKEN available to the job. CHANT_GITLAB_TOKEN is read first where the two must differ.");
+}
+/** GitLab's REST paths take a URL-encoded project id or `group%2Fproject` path. */
+function notesEndpoint(ctx) {
+    return `${ctx.api}/projects/${encodeURIComponent(ctx.project)}/merge_requests/${ctx.iid}/notes`;
+}
+/** One GitLab REST call, with the failure spelled out rather than swallowed into a parse error. */
+async function gitlabRequest(url, token, init, signal) {
+    const res = await fetch(url, {
+        ...init,
+        ...(signal ? { signal } : {}),
+        headers: { [token.header]: token.value, "content-type": "application/json" },
+    });
+    if (!res.ok) {
+        const detail = (await res.text().catch(() => "")).slice(0, 500);
+        throw new Error(`GitLab API ${init.method ?? "GET"} ${url} answered ${res.status}${detail ? `: ${detail}` : ""} ` +
+            `(token from ${token.source}, sent as ${token.header}).`);
+    }
+    return res;
+}
+/**
+ * Find the note this Op already owns on `ctx`'s merge request, by the same
+ * hidden marker `comment` mode looks a GitHub comment up by: the
+ * marker is the body's first line and the match is a prefix.
+ *
+ * Pages the way GitLab pages, following the `x-next-page` response header
+ * rather than guessing a page count — an active merge request runs past one
+ * page of notes routinely, and a lookup that read page one alone would post
+ * a second comment instead of editing the first.
+ *
+ * GitLab's own system notes are skipped: they are the activity feed
+ * ("changed the description"), they are never ours, and they are the bulk of
+ * what fills those pages.
+ */
+async function findOwnedNote(ctx, token, marker, signal) {
+    const endpoint = notesEndpoint(ctx);
+    // A merge request with more notes than this has something other than a
+    // stale plan comment wrong with it; the bound is what stops a broken
+    // `x-next-page` header from looping forever.
+    const MAX_PAGES = 50;
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const res = await gitlabRequest(`${endpoint}?per_page=100&page=${page}`, token, { method: "GET" }, signal);
+        const notes = (await res.json());
+        const owned = notes.find((note) => !note.system && (note.body ?? "").startsWith(marker));
+        if (owned)
+            return owned.id;
+        const next = res.headers.get("x-next-page")?.trim();
+        if (!next)
+            return undefined;
+    }
+    return undefined;
+}
+/**
+ * Post `body` as one note on `ctx`'s merge request, or edit the note this Op
+ * already owns there — {@link postOrUpdateComment}'s GitLab half, and the
+ * same recipe: find by marker, PUT when there is one, POST when there is not,
+ * so a merge request pushed to five times carries one note holding the
+ * current finding rather than five stale ones.
+ *
+ * Over `fetch` rather than a CLI: `glab` is on no GitLab runner by default,
+ * and a job whose finding step depended on it would fail on the ordinary
+ * `node:22` image the generator emits. The GitHub and Forgejo half
+ * follows the same rule since #3757.
+ */
+async function postOrUpdateNote(ctx, token, marker, body, signal) {
+    const endpoint = notesEndpoint(ctx);
+    const existing = await findOwnedNote(ctx, token, marker, signal);
+    const payload = JSON.stringify({ body: `${marker}\n\n${body}` });
+    const res = existing
+        ? await gitlabRequest(`${endpoint}/${existing}`, token, { method: "PUT", body: payload }, signal)
+        : await gitlabRequest(endpoint, token, { method: "POST", body: payload }, signal);
+    const note = (await res.json());
+    // GitLab's note payload carries no web URL, unlike GitHub's comment. The
+    // anchor is how the UI itself addresses a note, so it is built rather than
+    // read; with no project web URL to build it from, the API path is at least
+    // a resolvable address for the thing that was written.
+    return ctx.webUrl
+        ? `${ctx.webUrl}/-/merge_requests/${ctx.iid}#note_${note.id}`
+        : `${endpoint}/${note.id}`;
+}
+/** GitLab's REST path for a project's issues. */
+function issuesEndpoint(ctx) {
+    return `${ctx.api}/projects/${encodeURIComponent(ctx.project)}/issues`;
+}
+/**
+ * Find the issue this Op already owns in `ctx`'s project, by the same hidden
+ * marker `findOwnedNote` looks a merge-request note up by: the marker is the
+ * description's first line and the match is a prefix.
+ *
+ * `search`/`in=description` narrows the request server-side to issues whose
+ * description contains the marker, rather than paging every issue the
+ * project has ever opened — a long-lived project accumulates issues the way
+ * an active merge request accumulates notes, and the marker is exact text a
+ * full-text search matches reliably. The `startswith` check after the fetch
+ * still decides ownership, the same as the note lookup, since `search` finds
+ * the marker anywhere in the field and only a match at the very start is
+ * this Op's own issue rather than one that happens to quote it.
+ *
+ * Paged the way GitLab pages, following the `x-next-page` response header —
+ * see {@link findOwnedNote} for why a bounded loop rather than a guessed page
+ * count.
+ */
+async function findOwnedIssue(ctx, token, marker, signal) {
+    const endpoint = issuesEndpoint(ctx);
+    const MAX_PAGES = 50;
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const res = await gitlabRequest(`${endpoint}?per_page=100&page=${page}&search=${encodeURIComponent(marker)}&in=description`, token, { method: "GET" }, signal);
+        const issues = (await res.json());
+        const owned = issues.find((issue) => (issue.description ?? "").startsWith(marker));
+        if (owned)
+            return owned.iid;
+        const next = res.headers.get("x-next-page")?.trim();
+        if (!next)
+            return undefined;
+    }
+    return undefined;
+}
+/**
+ * Open `title`/`body` as one issue in `ctx`'s project, or edit the issue this
+ * Op already owns there — {@link postOrUpdateNote}'s issue counterpart, and
+ * the same recipe: find by marker, PUT when there is one, POST when there is
+ * not, so a cron Op that finds drift every night carries one issue holding
+ * the current finding rather than a new one each run (#2292).
+ *
+ * `title` is written on every call, POST or PUT, so the issue's headline
+ * stays current (e.g. an entry count) even though only the description's
+ * marker is what makes the issue findable again.
+ */
+async function postOrUpdateIssue(ctx, token, marker, title, body, signal) {
+    const endpoint = issuesEndpoint(ctx);
+    const existing = await findOwnedIssue(ctx, token, marker, signal);
+    const payload = JSON.stringify({ title, description: `${marker}\n\n${body}` });
+    const res = existing
+        ? await gitlabRequest(`${endpoint}/${existing}`, token, { method: "PUT", body: payload }, signal)
+        : await gitlabRequest(endpoint, token, { method: "POST", body: payload }, signal);
+    const issue = (await res.json());
+    // GitLab does return a `web_url` on an issue payload, unlike a note, but
+    // building it from the project's own web URL keeps this symmetric with
+    // `postOrUpdateNote` and needs no extra field pinned in tests.
+    return ctx.webUrl ? `${ctx.webUrl}/-/issues/${issue.iid}` : `${endpoint}/${issue.iid}`;
+}
+/**
+ * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
+ * `noop` entries (nothing to reconcile). Pure — exported for testing.
+ */
+export function entriesFromPlan(planJson) {
+    const cs = JSON.parse(planJson);
+    return (cs.entries ?? [])
+        .filter((e) => e.action !== "noop")
+        .map((e) => ({ name: e.name, action: e.action, type: e.type }));
+}
+/** Derive reconcile entries from `chant lifecycle plan`. */
+async function derivePlanEntries(env, owned, signal) {
+    const ownedFlag = owned ? " --owned" : "";
+    const { stdout } = await execAsync(`chant lifecycle plan ${shellQuote(env)}${ownedFlag} --json`, { signal });
+    return entriesFromPlan(stdout);
+}
+/**
+ * The marker the run will write and find its finding by, for the two modes
+ * that have one, or `undefined` for the two that do not (#2319, and its
+ * pre-merge review).
+ *
+ * Pure, and called before anything else in {@link reconcilePr} so that both
+ * refusals it can raise — no identity, unusable marker — happen before the
+ * activity shells out to anything.
+ *
+ * `issue` mode requires an identity: the Op's name, or a marker the caller
+ * keeps unique. `comment` mode does not, because its marker is scoped to one
+ * pull request rather than to the repository — see `ReconcilePrArgs.op` and
+ * {@link issueMarker} for that asymmetry and what is tracked separately.
+ * Both modes get the same {@link suppliedMarker} treatment of the field,
+ * because a blank or unusable marker is a property of the field, not of the
+ * mode reading it.
+ */
+function resolveMarker(mode, args) {
+    if (mode === "issue") {
+        const supplied = suppliedMarker(args.marker);
+        const op = args.op?.trim();
+        if (!supplied && !op)
+            throw new Error(noIssueIdentityMessage(args.env));
+        return supplied ?? issueMarker(op, args.env);
+    }
+    if (mode === "comment") {
+        return suppliedMarker(args.marker) ?? commentMarker(args.env);
+    }
+    return undefined;
+}
+/**
+ * Reconcile activity: turn regenerated TypeScript into a reviewable artifact.
+ *
+ * - `report` — return the summary only; no git, no network.
+ * - `issue` — open or edit one issue describing the drift (no code change).
+ *   On a GitHub Actions or Forgejo Actions job, or GitHub Enterprise Server,
+ *   the OPEN issue already carrying this Op's hidden marker is edited in
+ *   place and a new one opened only when there is none (#2297). On a GitLab
+ *   CI job (any trigger — the point of this mode is a cron run that has no
+ *   merge request), the same recipe against one GitLab issue (#2292). Neither
+ *   branch ever closes the issue itself — see {@link postOrUpdateGithubIssue}
+ *   for that decision and why. The marker names the Op as well as the env
+ *   (#2319), so the step needs `op` or an explicit `marker` and fails by name
+ *   with neither; an issue left over from the pre-#2319 env-only marker
+ *   matches no Op's marker now and is left where it is, unedited, rather than
+ *   adopted by whichever Op happens to run first.
+ * - `comment` — post the body as one comment on the pull request that
+ *   triggered the run, editing that same comment on every re-run rather than
+ *   stacking a new one (#2231) — on GitHub and on Forgejo alike (#2291), the
+ *   same GitHub-shaped `issues/{n}/comments` calls against each host's own
+ *   API base — or, on a GitLab `merge_request_event` pipeline, as one note on
+ *   that merge request by the same recipe (#2256). Needs a pull-request- or
+ *   merge-request-triggered run; fails by name when there is none. No code
+ *   change, and the `pull-requests: write` the generated workflow already
+ *   grants on that trigger is the whole scope it spends on GitHub and
+ *   Forgejo; on GitLab the scope is whatever the token it is given carries.
+ * - `pull-request` — create a branch, regenerate source via
+ *   `chant import --from <env>`, commit, push, and open a PR whose diff is the
+ *   regenerated TypeScript. Never commits to the main branch.
+ *
+ * The body is {@link reconcileSummary}'s change-set table unless `args.body`
+ * supplies one, in which case that text is used verbatim and no plan is
+ * derived (chant #2087).
+ *
+ * Requires `chant` in the environment. `comment` and `issue` reach the forge
+ * over `fetch` and need nothing else in CI (#3757); `pull-request` needs `git`
+ * and `gh`, and so does an `issue` run outside any CI job, which leaves the
+ * credential to `gh auth login`.
+ */
+export async function reconcilePr(args, signal) {
+    const mode = args.mode ?? "pull-request";
+    const owned = args.owned ?? false;
+    // Resolved first, ahead of the `chant lifecycle plan` shell-out below
+    // (#2319 pre-merge review). The identity refusal used to sit inside the
+    // `issue` branch, which is after that derivation, so the arg shape that
+    // actually reaches it — `{ env, op, mode, owned }`, `ReconcileOp`'s own,
+    // with no `body` to short-circuit the plan — ran a shell command before
+    // failing. `chant lifecycle plan` is read-only, so nothing was written; but
+    // a plan that fails first hands the operator a plan error in place of the
+    // named refusal this design rests on, which is the whole point of refusing
+    // by name.
+    const resolvedMarker = resolveMarker(mode, args);
+    // A caller-supplied body means the finding is already written, so there is
+    // nothing for `chant lifecycle plan` to tell us (#2087).
+    const entries = args.entries ?? (args.body !== undefined ? [] : await derivePlanEntries(args.env, owned, signal));
+    const summary = args.body ?? reconcileSummary(args.env, entries);
+    const title = args.title ?? `Reconcile ${args.env}: ${entries.length} change(s) from live`;
+    if (mode === "report") {
+        return { mode, summary, entries };
+    }
+    if (mode === "issue") {
+        // Non-null because `resolveMarker` returns a string for this mode or
+        // throws, and it already ran at the top of the function.
+        const marker = resolvedMarker;
+        // GitLab first, because its check is the narrow one: `CI_PROJECT_ID` is
+        // set on every GitLab CI job, and nothing outside GitLab CI sets it
+        // (#2292) — see `gitlabProjectContextFrom`.
+        const project = gitlabProjectContextFrom(process.env);
+        if (project) {
+            const token = gitlabNoteTokenFrom(process.env);
+            if (!token)
+                throw new Error(noGitlabIssueTokenMessage(project.project));
+            const issueUrl = await postOrUpdateIssue(project, token, marker, title, summary, signal);
+            return { mode, summary, entries, issueUrl };
+        }
+        // GitHub, GHES, or Forgejo next: any job that ran under GitHub Actions or
+        // Forgejo Actions carries GITHUB_REPOSITORY (#2297). The issue is kept
+        // through the forge client (#3757) — see postOrUpdateGithubIssue's doc
+        // comment for why the lookup pages rather than searches, and for the
+        // close decision.
+        const repo = process.env.GITHUB_REPOSITORY;
+        if (repo) {
+            const token = commentTokenFrom(process.env);
+            if (!token)
+                throw new Error(noIssueTokenMessage(repo));
+            const forge = githubShapedForgeFrom(process.env, repo, token, signal);
+            const issueUrl = await withTokenSource(token, () => forge.upsertIssue(marker, title, `${marker}\n\n${summary}`));
+            return { mode, summary, entries, issueUrl };
+        }
+        // Outside any known CI job (a local or manual invocation): fall back to
+        // gh's own ambient repo detection, unchanged from before #2297. The
+        // marker is still written here — it costs nothing, and means a later CI
+        // run of the same Op finds and edits this issue instead of opening a
+        // second one.
+        //
+        // This is the one path that does NOT go through `commentTokenFrom`
+        // (#2320), deliberately. It is reached only when the run is outside every
+        // CI job chant recognizes, which is where `gh auth login`'s stored
+        // credential is the credential — and that is a login `commentTokenFrom`
+        // cannot see, so refusing on a missing environment variable here would
+        // reject the exact setup the branch exists to serve. `gh` still reads
+        // GH_TOKEN and GITHUB_TOKEN off this process's own environment if they
+        // are set; what it does not get is CHANT_FORGEJO_TOKEN promoted into
+        // GH_TOKEN, because promoting it would silently outrank the login the
+        // operator is standing in front of.
+        const { stdout } = await execAsync(`gh issue create --title ${shellQuote(title)} --body ${shellQuote(`${marker}\n\n${summary}`)}`, { signal });
+        return { mode, summary, entries, issueUrl: stdout.trim() };
+    }
+    if (mode === "comment") {
+        // The trigger context is read here rather than passed in: a step's args
+        // are serialized at build time, and the pull request is not known until
+        // the run. Missing context is fatal — see `noPullRequestContextMessage`.
+        const marker = resolvedMarker;
+        // GitLab first, because its check is the narrow one: only a
+        // `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID` (#2256), so
+        // a run that has it is unambiguously the GitLab case, and a GitHub run
+        // never reaches this branch.
+        const mr = mergeRequestContextFrom(process.env);
+        if (mr) {
+            const token = gitlabNoteTokenFrom(process.env);
+            if (!token)
+                throw new Error(noGitlabNoteTokenMessage(mr.iid));
+            const commentUrl = await postOrUpdateNote(mr, token, marker, summary, signal);
+            return {
+                mode,
+                summary,
+                entries,
+                commentUrl,
+                mergeRequest: `${mr.path ?? mr.project}!${mr.iid}`,
+            };
+        }
+        const ctx = await resolvePullRequestContext();
+        const commentUrl = await postOrUpdateComment(ctx, marker, summary, signal);
+        return { mode, summary, entries, commentUrl, pullRequest: `${ctx.repo}#${ctx.number}` };
+    }
+    // pull-request
+    const branch = args.branch ?? reconcileBranchName(args.env);
+    const output = args.output ?? "./infra";
+    const ownedFlag = owned ? " --owned" : "";
+    // Never touch the main branch: cut a fresh branch first.
+    await execAsync(`git checkout -b ${shellQuote(branch)}`, { signal });
+    await execAsync(`chant import --from ${shellQuote(args.env)}${ownedFlag} --output ${shellQuote(output)} --force`, { signal });
+    await execAsync(`git add ${shellQuote(output)}`, { signal });
+    await execAsync(`git commit -m ${shellQuote(title)}`, { signal });
+    await execAsync(`git push -u origin ${shellQuote(branch)}`, { signal });
+    // `gh pr` speaks GraphQL, which Forgejo does not serve, and GitLab has no
+    // `gh`: a Forgejo or GitLab job opens the pull request over REST (#3798).
+    const forge = await restPullRequestForge(process.env, { fetch: (url, init) => globalThis.fetch(url, { ...init, ...(signal ? { signal } : {}) }) });
+    if (forge) {
+        const pr = await forge.openPullRequest({ head: branch, title, body: summary });
+        return { mode, branch, summary, entries, prUrl: pr.url ?? "" };
+    }
+    // `gh pr create` names no host, so on GitHub Enterprise Server it is told
+    // the job's own (#3780). See `./gh-host.ts`.
+    const { stdout } = await execAsync(`gh pr create --title ${shellQuote(title)} --body ${shellQuote(summary)} --head ${shellQuote(branch)}`, { signal, env: await ghHostEnv(process.env) });
+    return { mode, branch, summary, entries, prUrl: stdout.trim() };
+}