@intentius/chant 0.62.0 → 0.63.0

package/src/op/activities/reconcile.ts

@@ -37,16 +37,46 @@ const execAsync = promisify(exec);
  * sets `GITHUB_REPOSITORY`. Both are sticky now (chant #2292, #2297): each
  * finds and edits the OPEN issue it already owns by a hidden marker, the same
  * recipe `comment` mode's note uses, and opens a new one only when it finds
+ * none. Which is why that marker has to name the Op (chant #2319) and why
+ * this mode refuses a step that supplies neither an `op` nor a `marker` — see
+ * {@link issueMarker} and {@link noIssueIdentityMessage}.
+ *
  * none. See {@link postOrUpdateGithubIssue} for the GitHub/GHES/Forgejo half
  * — including why it does not use GitHub's Search API, and the decision that
  * this mode never closes the issue itself. Only a run outside any known CI
  * job — no `CI_PROJECT_ID`, no `GITHUB_REPOSITORY` — falls back to `gh issue
  * create`'s own ambient repo detection, still marker-prefixed so a later CI
- * run of the same Op finds and edits it instead of opening a second one. `gh
- * api` was not exercised against a real Forgejo instance for this mode (only
- * the `comment` mode's endpoints were, chant #2291) — the request shape
- * mirrors that mode's exactly, but the search behavior itself is the one
- * part a mock cannot vouch for.
+ * run of the same Op finds and edits it instead of opening a second one.
+ *
+ * The credential did not always travel (chant #2320). The URL and the
+ * GET/PATCH/POST triple matched `postOrUpdateComment`'s, but that function
+ * resolved a token through {@link commentTokenFrom} and forwarded it as
+ * `GH_TOKEN` while the issue path forwarded no environment at all, so
+ * `CHANT_FORGEJO_TOKEN` never reached `gh`. Both paths now resolve the same
+ * way, in the same order, and forward the same variable, with the two
+ * refusals differing only in what they name ({@link noCommentTokenMessage},
+ * {@link noIssueTokenMessage}). The one deliberate exception is the `gh issue
+ * create` fallback above, which runs outside every CI job and so leaves the
+ * credential to `gh auth login` — see the comment on that branch. Parity with
+ * `comment` mode is not a working Forgejo write, as the next paragraph says.
+ *
+ * Settled against a real Forgejo 12.0.4+gitea-1.22.0 instance under chant
+ * #2315, the way `comment` mode's endpoints were under #2291: the *read*
+ * half works — plain paginated listing (no `/search/issues`, confirmed
+ * absent from Forgejo's own OpenAPI spec) and the `.pull_request == null`
+ * filter both behave exactly as they do against github.com. The *write*
+ * half does not, for a reason no mock could have caught: `gh`'s own
+ * `GH_TOKEN`/`GITHUB_TOKEN` only authenticate a request to github.com or a
+ * ghe.com subdomain (`gh help environment`), never a self-hosted Forgejo,
+ * and this function's POST/PATCH calls (like `postOrUpdateComment`'s) carry
+ * only `GH_TOKEN` — no `GH_HOST`, no `GH_ENTERPRISE_TOKEN`. Every write this
+ * mode makes on a real Forgejo instance fails with `{"message":"token is
+ * required"}` (HTTP 401), confirmed with `GH_DEBUG=api` sending no
+ * `Authorization` header at all. The forgejo Op generator refuses
+ * `findingMode: "issue"` by name for this reason (chant #2315); this
+ * activity's own behavior is unchanged; a hand-authored (non-generated)
+ * workflow that calls it directly against a Forgejo host will hit the same
+ * 401 the generator now refuses to produce.
  */
 export type ReconcileMode = "pull-request" | "issue" | "report" | "comment";
 
@@ -79,13 +109,33 @@ export interface ReconcilePrArgs {
   owned?: boolean;
   /** PR / issue title. Default derived from env. */
   title?: string;
+  /**
+   * The name of the Op this step belongs to, which is what makes an `issue`
+   * mode marker unique (#2319) — see {@link issueMarker}. Set it to the
+   * enclosing `Op`'s own `name`; both in-tree composites do, and a
+   * hand-written step should too.
+   *
+   * `issue` mode needs this or an explicit `marker`, and refuses by name
+   * ({@link noIssueIdentityMessage}) with neither: without one the marker
+   * falls back to naming only the env, two Ops over one env collide on it,
+   * and each nightly run silently overwrites the other's report.
+   *
+   * `comment` mode ignores it. That mode's marker is scoped to one pull
+   * request rather than to the repository, so its collision (two `comment`
+   * Ops over one env, both triggered by one pull request) is bounded by that
+   * pull request's life and leaves nothing behind. Tracked separately rather
+   * than folded in here, because changing `commentMarker` would orphan the
+   * comments already sitting on open pull requests.
+   */
+  op?: string;
   /**
    * Hidden marker identifying this Op's own comment or issue. The activity
    * writes it as the first line and finds it again by it on the next run, so
    * a re-run edits one comment/issue instead of stacking a new one. Default:
-   * {@link commentMarker} for `comment` mode, {@link issueMarker} for `issue`
-   * mode, both keyed on `env`, so two Ops over two roots get two comments (or
-   * two issues) and each updates in place.
+   * {@link commentMarker} for `comment` mode, keyed on `env`; {@link
+   * issueMarker} for `issue` mode, keyed on `op` and `env` together. Supply
+   * it directly to own uniqueness yourself — in `issue` mode that is the one
+   * way to satisfy the identity requirement without passing `op`.
    */
   marker?: string;
   /**
@@ -177,21 +227,132 @@ export interface PullRequestContext {
  * environments own two comments and each updates in place.
  */
 export function commentMarker(env: string): string {
-  return `<!-- chant-reconcile:${env.replace(/[^a-zA-Z0-9._-]+/g, "-")} -->`;
+  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: string, env: string): string {
+  return `<!-- chant-reconcile-issue:${markerSlug(op)}/${markerSlug(env)} -->`;
+}
+
+/** The slugify both markers share: everything outside `[A-Za-z0-9._-]` collapses to `-`. */
+function markerSlug(s: string): string {
+  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: string): string {
+  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: string | undefined): string | undefined {
+  const trimmed = marker?.trim();
+  if (!trimmed) return undefined;
+  if (/["\\]|[\u0000-\u001f\u007f]/.test(trimmed)) throw new Error(unsafeMarkerMessage(trimmed));
+  return trimmed;
 }
 
 /**
- * The hidden marker that makes an `issue`-mode GitLab finding findable across
- * re-runs (#2292): written as the issue description's first line, matched by
- * a server-side `search` plus a `startswith` check on the next run — 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`.
- * Slugified the same way, for the same reason: interpolated next to quotes
- * and URL-encoding it should not need escaping out of.
+ * 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 issueMarker(env: string): string {
-  return `<!-- chant-reconcile-issue:${env.replace(/[^a-zA-Z0-9._-]+/g, "-")} -->`;
+export function noIssueIdentityMessage(env: string): string {
+  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. */
@@ -334,6 +495,16 @@ export function noCommentTokenMessage(repo: string, number: number): string {
   );
 }
 
+/** What an `issue`-mode step says on a repository it has no credential for (#2320). */
+export function noIssueTokenMessage(repo: string): string {
+  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."
+  );
+}
+
 /**
  * Post `body` as one comment on `ctx`'s pull request, or edit the comment this
  * Op already owns there. The sticky-comment recipe the github lexicon's
@@ -395,12 +566,23 @@ async function postOrUpdateComment(
  * Minimal `gh` invocation shape {@link postOrUpdateGithubIssue} threads its
  * calls through. `reconcilePr` wraps `execAsync` (carrying its own `signal`)
  * to this shape; `lexiconUpgrade` passes its injectable `GhRunner` straight
- * through, since the two already share the same `(cmd) => Promise<{ stdout,
- * stderr }>` signature. One function, not two copies, because the recipe
- * below — search, then PATCH or POST — is identical for both callers; only
- * the issue's title/body and the marker that owns it differ.
+ * through, since the two already share this signature. One function, not two
+ * copies, because the recipe below — search, then PATCH or POST — is
+ * identical for both callers; only the issue's title/body and the marker that
+ * owns it differ.
+ *
+ * The `opts` argument exists so `postOrUpdateGithubIssue` can hand `gh` the
+ * token it resolved (chant #2320) rather than leaving `gh` to find one
+ * ambiently. A caller that adds nothing of its own can ignore it and pass it
+ * straight to `exec`; `reconcilePr` merges it with the `signal` it already
+ * carries. It is deliberately not a whole `ExecOptions`: an implementation
+ * that had to honour `cwd` or `shell` too would be a second exec wrapper, and
+ * the point of this type is that there is only one.
  */
-export type GhExec = (cmd: string) => Promise<{ stdout: string; stderr: string }>;
+export type GhExec = (
+  cmd: string,
+  opts?: { env?: NodeJS.ProcessEnv },
+) => Promise<{ stdout: string; stderr: string }>;
 
 /**
  * Open `title`/`body` as one GitHub-shaped issue in `repo`, or edit the issue
@@ -415,6 +597,21 @@ export type GhExec = (cmd: string) => Promise<{ stdout: string; stderr: string }
  * same as `postOrUpdateComment` (#2291) — so this reaches GitHub Enterprise
  * Server the same way it reaches github.com.
  *
+ * The credential is resolved and forwarded the same way too (chant #2320),
+ * through {@link commentTokenFrom} and out as `GH_TOKEN` 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`
@@ -428,9 +625,9 @@ export type GhExec = (cmd: string) => Promise<{ stdout: string; stderr: string }
  *    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: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
+ *    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.
@@ -441,7 +638,15 @@ export type GhExec = (cmd: string) => Promise<{ stdout: string; stderr: string }
  *    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).
+ *    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 do not clear the same instance — see the
+ *    module doc's `issue` bullet for why, and why the forgejo Op generator
+ *    refuses this mode rather than generating a job that would 401 on every
+ *    run.
  *
  * So this reuses the recipe `postOrUpdateComment` already proved for PR
  * comments: list, `--paginate`, filter with `--jq` by an exact `startswith`
@@ -479,13 +684,20 @@ export async function postOrUpdateGithubIssue(
   body: string,
   exec: GhExec,
 ): Promise<string> {
+  const token = commentTokenFrom(process.env);
+  if (!token) throw new Error(noIssueTokenMessage(repo));
+  const env = { ...process.env, GH_TOKEN: token.value };
+
   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)}`);
+  const { stdout: found } = await exec(
+    `gh api ${shellQuote(listUrl)} --paginate --jq ${shellQuote(jq)}`,
+    { env },
+  );
   // `--paginate` prints one `--jq` result per page, same as postOrUpdateComment.
   const existing = found.split("\n").map((l) => l.trim()).find((l) => /^\d+$/.test(l));
   const titleField = shellQuote(`title=${title}`);
@@ -495,11 +707,13 @@ export async function postOrUpdateGithubIssue(
     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();
 }
@@ -896,6 +1110,36 @@ async function derivePlanEntries(
   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: ReconcileMode, args: ReconcilePrArgs): string | undefined {
+  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 as string, args.env);
+  }
+  if (mode === "comment") {
+    return suppliedMarker(args.marker) ?? commentMarker(args.env);
+  }
+  return undefined;
+}
+
 /**
  * Reconcile activity: turn regenerated TypeScript into a reviewable artifact.
  *
@@ -907,7 +1151,11 @@ async function derivePlanEntries(
  *   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.
+ *   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
@@ -931,6 +1179,18 @@ async function derivePlanEntries(
 export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal): Promise<ReconcileResult> {
   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));
@@ -942,7 +1202,9 @@ export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal):
   }
 
   if (mode === "issue") {
-    const marker = args.marker ?? issueMarker(args.env);
+    // 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
@@ -961,8 +1223,8 @@ export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal):
     // the close decision.
     const repo = process.env.GITHUB_REPOSITORY;
     if (repo) {
-      const issueUrl = await postOrUpdateGithubIssue(repo, marker, title, summary, (cmd) =>
-        execAsync(cmd, { signal }),
+      const issueUrl = await postOrUpdateGithubIssue(repo, marker, title, summary, (cmd, opts) =>
+        execAsync(cmd, { signal, ...opts }),
       );
       return { mode, summary, entries, issueUrl };
     }
@@ -972,6 +1234,17 @@ export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal):
     // 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 },
@@ -983,7 +1256,7 @@ export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal):
     // 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 = args.marker ?? commentMarker(args.env);
+    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

package/src/op/builders.ts

@@ -107,16 +107,22 @@ export function activity(
  * that reaches this step with no resolution newer than its pending fact
  * records the pending fact and ends `gated`. `chant approve <op> <gate>`
  * writes the resolution, and the next run walks through carrying the approver.
+ *
+ * Pass `plan` to bind the approval to a specific plan (#2300) — normally the
+ * Plan phase's own digest, `plan.out.planDigest`. Then a resolution counts
+ * only for that plan, and a run whose fresh plan differs is refused by name
+ * instead of applying a change nobody approved. See {@link GateStep.plan}.
  */
 export function gate(
   name: string,
-  opts?: { timeout?: string; description?: string },
+  opts?: { timeout?: string; description?: string; plan?: GateStep["plan"] },
 ): GateStep {
   return {
     kind: "gate",
     gate: name,
     ...(opts?.timeout ? { timeout: opts.timeout } : {}),
     ...(opts?.description ? { description: opts.description } : {}),
+    ...(opts?.plan !== undefined ? { plan: opts.plan } : {}),
   };
 }
 

package/src/op/composites/apply-op.ts

@@ -19,6 +19,12 @@
  * approve <op> <gate>` line to run. Approve, run again, and the same Op
  * converges — no durable workflow engine is involved.
  *
+ * The gate binds the plan (#2300). The Plan phase's `lifecycleDiff` publishes
+ * a digest of its change set, the gate step references it, and a resolution
+ * counts only for that digest. Approve, change the declared source, re-run,
+ * and the run stops again with both digests named rather than applying a
+ * change set the approver never saw.
+ *
  * @example
  * ```typescript
  * // additive, local executor
@@ -38,6 +44,7 @@
  */
 
 import { Op, phase, activity, gate } from "../builders";
+import { stepOutput } from "../step-output-ref";
 import { gateName } from "../gate-name";
 import type { OpResource } from "../resource";
 import { defaultOutput, hasNativeRollback, type ApplyTarget, type DeleteMode } from "../activities/apply";
@@ -129,6 +136,10 @@ export function ApplyOp(config: ApplyOpConfig): ApplyOpResources {
     phase("Plan", [
       {
         kind: "activity" as const,
+        // #2300: the gate below references this step's digest, and a
+        // reference needs an id. `plan` rather than `diff`, because what the
+        // Approve phase binds to is the plan this step produced.
+        id: "plan",
         fn: "lifecycleDiff",
         args: { env: config.env, live: true },
         outcomeAttribute: { name: "Drift", from: "drifted" },
@@ -141,6 +152,11 @@ export function ApplyOp(config: ApplyOpConfig): ApplyOpResources {
       phase("Approve", [
         gate(gateName(config.gate ?? {}) || `approve-${config.name}`, {
           ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
+          // #2300: the approval is for the change set the Plan phase just
+          // produced. Edit the source between approving and re-running and
+          // the gate refuses, naming the approved digest and the planned one,
+          // instead of applying what nobody read.
+          plan: stepOutput("plan", "planDigest"),
           description:
             config.gate?.description ??
             `Approve apply to ${config.env} (delete mode: ${deleteMode}` +

package/src/op/composites/composites.test.ts

@@ -12,6 +12,7 @@ import { ReconcileOp } from "./reconcile-op";
 import { ApplyOp } from "./apply-op";
 import { DECLARABLE_MARKER } from "../../declarable";
 import { EffectReceipt, receiptExpectation } from "../../effect-receipt";
+import { isStepOutputRef } from "../step-output-ref";
 
 function getProps(entity: unknown): Record<string, unknown> {
   return (entity as { props: Record<string, unknown> }).props;
@@ -115,14 +116,14 @@ describe("ReconcileOp: configuration", () => {
     expect(phases.map((p) => p.name)).toEqual(["Snapshot", "Plan", "Reconcile"]);
     const reconcileStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
     expect(reconcileStep.fn).toBe("reconcilePr");
-    expect(reconcileStep.args).toEqual({ env: "prod", mode: "pull-request", owned: false });
+    expect(reconcileStep.args).toEqual({ env: "prod", op: "p", mode: "pull-request", owned: false });
   });
 
   test("scope.owned + onDrift flow into the reconcilePr step", () => {
     const { op } = ReconcileOp({ name: "p", env: "prod", onDrift: "issue", scope: { owned: true } });
     const phases = getProps(op).phases as Array<Record<string, unknown>>;
     const reconcileStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
-    expect(reconcileStep.args).toEqual({ env: "prod", mode: "issue", owned: true });
+    expect(reconcileStep.args).toEqual({ env: "prod", op: "p", mode: "issue", owned: true });
   });
 
   test("labels include Reconcile + Env", () => {
@@ -204,6 +205,18 @@ describe("ApplyOp: gating + deletes", () => {
     const { op } = ApplyOp({ name: "p", env: "prod" });
     expect(getProps(op).labels).toEqual({ Apply: "true", Env: "prod" });
   });
+
+  // #2300 — the gate approves the change set the Plan phase produced, not the
+  // next run of the Op. The Plan step carries the id the reference needs.
+  test("the gate binds the Plan phase's own change-set digest", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", delete: "gated" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const planStep = (phases[1].steps as Array<Record<string, unknown>>)[0];
+    expect(planStep.id).toBe("plan");
+    const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(isStepOutputRef(gateStep.plan)).toBe(true);
+    expect(gateStep.plan).toMatchObject({ step: "plan", path: "planDigest" });
+  });
 });
 
 describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {

package/src/op/composites/reconcile-op.test.ts

@@ -34,6 +34,24 @@ describe("ReconcileOp composite — PR/issue URL outcome (#8)", () => {
   });
 });
 
+describe("ReconcileOp composite — the finding step names its Op (#2319)", () => {
+  test("passes the Op's own name as `op`, which is what keeps the issue marker unique", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod", onDrift: "issue" });
+    expect((reconcileStep(op).args as { op: string }).op).toBe("prod-reconcile");
+  });
+
+  test("two Ops over one env carry two identities", () => {
+    // The collision #2319 reports: `env` alone is shared here by construction,
+    // and a `TerraformWatchOp` over a root named "prod" would share it too.
+    const a = ReconcileOp({ name: "prod-reconcile", env: "prod", onDrift: "issue" });
+    const b = ReconcileOp({ name: "prod-reconcile-owned", env: "prod", onDrift: "issue" });
+    const argsA = reconcileStep(a.op).args as { op: string; env: string };
+    const argsB = reconcileStep(b.op).args as { op: string; env: string };
+    expect(argsA.env).toBe(argsB.env);
+    expect(argsA.op).not.toBe(argsB.op);
+  });
+});
+
 describe("ReconcileOp composite — cadence on the op (#2120)", () => {
   function opProps(op: unknown): Record<string, unknown> {
     return (op as { props: Record<string, unknown> }).props;

package/src/op/composites/reconcile-op.ts

@@ -96,10 +96,16 @@ export function ReconcileOp(config: ReconcileOpConfig): ReconcileOpResources {
         // regenerates via `chant import --from`, and opens a PR. Surface the
         // opened PR/issue URL as an outcome so `chant run` prints it — the
         // reconcile's result is the link.
+        //
+        // `op` names this Op in the marker `issue` mode's sticky issue is
+        // found by (#2319). The env alone is not unique across Ops: it shares
+        // a marker namespace with `TerraformWatchOp`, which passes a terraform
+        // *root* as its `env`, so a chant environment and a root that happen
+        // to share a name resolved to one marker and overwrote each other.
         {
           kind: "activity" as const,
           fn: "reconcilePr",
-          args: { env: config.env, mode: onDrift, owned },
+          args: { env: config.env, op: config.name, mode: onDrift, owned },
           ...(reconcileOutcome ? { outcomeAttribute: reconcileOutcome } : {}),
         },
       ]),