@intentius/chant 0.61.0 → 0.62.0

package/dist/op/activities/reconcile.d.ts

@@ -13,6 +13,34 @@
  * `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID`, a GitHub
  * `pull_request` event sets `GITHUB_REPOSITORY`, and no run sets both. See
  * {@link mergeRequestContextFrom}.
+ *
+ * On Forgejo the same mode posts the same GitHub-shaped comment (chant
+ * #2291): no forge split at all, because a Forgejo Actions job already sets
+ * `GITHUB_REPOSITORY`, `GITHUB_API_URL` and `github.token` the same way a
+ * GitHub Actions job does, and Forgejo's own `/api/v1` takes the identical
+ * GET/POST/PATCH triple. The one thing that needed fixing was the URL: `gh
+ * api` resolves a *relative* path against `/api/v3` for any host other than
+ * `github.com`, and Forgejo does not serve `/api/v3` — verified on a real
+ * Forgejo 12.0.4+gitea-1.22.0 instance during INTENTIUS/choudoufu#1027. See
+ * {@link postOrUpdateComment} and {@link githubApiBaseFrom}.
+ *
+ * `issue` needs no merge/pull request — its whole point is a cron trigger
+ * that has none — so its forge split reads off a wider signal: any GitLab CI
+ * job sets `CI_PROJECT_ID`, not only a merge-request one (see {@link
+ * gitlabProjectContextFrom}), and any GitHub Actions or Forgejo Actions job
+ * 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. 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.
  */
 export type ReconcileMode = "pull-request" | "issue" | "report" | "comment";
 /** A change-set entry that triggered reconciliation. */
@@ -44,11 +72,12 @@ export interface ReconcilePrArgs {
     /** PR / issue title. Default derived from env. */
     title?: string;
     /**
-     * Hidden marker identifying this Op's comment on the pull request (comment
-     * mode). The activity writes it as the comment's first line and finds the
-     * comment again by it on the next run, so a re-run edits one comment instead
-     * of stacking a new one. Default: {@link commentMarker} keyed on `env`, so
-     * two Ops over two roots get two comments and each updates in place.
+     * 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.
      */
     marker?: string;
     /**
@@ -74,7 +103,7 @@ export interface ReconcileResult {
     branch?: string;
     /** Opened PR URL (pull-request mode). */
     prUrl?: string;
-    /** Opened issue URL (issue mode). */
+    /** Opened or edited issue URL (issue mode; sticky on every forge — #2292, #2297). */
     issueUrl?: string;
     /** The posted or updated PR comment / MR note URL (comment mode). */
     commentUrl?: string;
@@ -110,6 +139,17 @@ export interface PullRequestContext {
  * environments own two comments and each updates in place.
  */
 export declare function commentMarker(env: string): string;
+/**
+ * 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.
+ */
+export declare function issueMarker(env: string): string;
 /** What a `comment`-mode step says when the run it is in has no pull request and no merge request. */
 export declare function noPullRequestContextMessage(): string;
 /**
@@ -128,6 +168,139 @@ export declare function pullRequestContextFrom(env: Record<string, string | unde
  * for it.
  */
 export declare function resolvePullRequestContext(env?: Record<string, string | undefined>): Promise<PullRequestContext>;
+/**
+ * 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 declare function githubApiBaseFrom(env: Record<string, string | undefined>): string;
+/** The credential a GitHub- or Forgejo-shaped comment call is made with. */
+export interface CommentToken {
+    value: string;
+    /** The variable it came from, so a refusal or a log line can name it. */
+    source: string;
+}
+/**
+ * Resolve the token `postOrUpdateComment` sends with, most specific first
+ * (chant #2291). `gh` itself already resolves `GH_TOKEN`/`GITHUB_TOKEN`
+ * ambiently from the process environment, and the generated workflow sets
+ * both 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.
+ * Resolving explicitly (rather than leaving it entirely to `gh`) also buys a
+ * named failure before the shell-out, in place of `gh`'s own opaque 401.
+ */
+export declare function commentTokenFrom(env: Record<string, string | undefined>): CommentToken | undefined;
+/** What a `comment`-mode step says on a pull request it has no credential for. */
+export declare function noCommentTokenMessage(repo: string, number: number): string;
+/**
+ * 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.
+ */
+export type GhExec = (cmd: string) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Open `title`/`body` as one GitHub-shaped issue in `repo`, or edit the issue
+ * this caller already owns there (#2297) — `postOrUpdateComment`'s issue
+ * counterpart, and the GitHub/GHES/Forgejo sibling of GitLab's
+ * `postOrUpdateIssue` (#2292): 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. Shared by `reconcilePr`'s own
+ * `issue` mode and `lexiconUpgrade`'s per-lexicon upgrade-status issue.
+ *
+ * Every call targets a full URL built from {@link githubApiBaseFrom}, the
+ * same as `postOrUpdateComment` (#2291) — so this reaches GitHub Enterprise
+ * Server the same way it reaches github.com.
+ *
+ * ## 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: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).
+ *
+ * So this reuses the recipe `postOrUpdateComment` 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 declare function postOrUpdateGithubIssue(repo: string, marker: string, title: string, body: string, exec: GhExec): Promise<string>;
 /**
  * The merge request a `comment`-mode run posts its note onto (#2256), as a
  * GitLab CI job knows it. The GitLab counterpart of {@link
@@ -161,6 +334,34 @@ export interface MergeRequestContext {
  * Returns undefined rather than throwing, so the caller owns the message.
  */
 export declare function mergeRequestContextFrom(env: Record<string, string | undefined>): MergeRequestContext | undefined;
+/**
+ * The GitLab project an `issue`-mode run opens or updates its issue on (#2292),
+ * as any GitLab CI job knows it — the counterpart of {@link
+ * mergeRequestContextFrom} for a mode that needs no merge request.
+ */
+export interface GitlabProjectContext {
+    /** REST v4 base, from `CI_API_V4_URL` or derived from `CI_SERVER_URL`. */
+    api: string;
+    /** The project holding the issue — its numeric id, or a `group/project` path. */
+    project: string;
+    /** `group/project`, for a human-readable result. */
+    path?: string;
+    /** The project's web URL, used to build the issue's own URL. */
+    webUrl?: string;
+}
+/**
+ * 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 declare function gitlabProjectContextFrom(env: Record<string, string | undefined>): GitlabProjectContext | undefined;
 /** The credential a merge-request note is written with, and the header GitLab reads it from. */
 export interface GitlabNoteToken {
     /** `PRIVATE-TOKEN` for a personal/project/group access token, `JOB-TOKEN` for `CI_JOB_TOKEN`. */
@@ -188,6 +389,8 @@ export interface GitlabNoteToken {
 export declare function gitlabNoteTokenFrom(env: Record<string, string | undefined>): GitlabNoteToken | undefined;
 /** What a `comment`-mode step says on a merge request it has no credential for. */
 export declare function noGitlabNoteTokenMessage(iid: number): string;
+/** What an `issue`-mode step says on a GitLab project it has no credential for (#2292). */
+export declare function noGitlabIssueTokenMessage(project: string): string;
 /**
  * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
  * `noop` entries (nothing to reconcile). Pure — exported for testing.
@@ -197,16 +400,24 @@ export declare function entriesFromPlan(planJson: string): ReconcileEntry[];
  * Reconcile activity: turn regenerated TypeScript into a reviewable artifact.
  *
  * - `report` — return the summary only; no git, no network.
- * - `issue` — open a GitHub issue describing the drift (no code change).
+ * - `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.
  * - `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), 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; on GitLab the scope is whatever the token it is given
- *   carries.
+ *   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.

package/dist/op/activities/reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/op/activities/reconcile.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,MAAM,CAkB/E;AAMD,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,sGAAsG;AACtG,wBAAgB,2BAA2B,IAAI,MAAM,CAWpD;AAeD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,YAAY,CAAC,EAAE,OAAO,GACrB,kBAAkB,GAAG,SAAS,CAOhC;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAAC,kBAAkB,CAAC,CAe7B;AA6CD;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,mBAAmB,GAAG,SAAS,CA2BjC;AAED,gGAAgG;AAChG,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,EAAE,eAAe,GAAG,WAAW,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,eAAe,GAAG,SAAS,CAQ7B;AAED,mFAAmF;AACnF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO5D;AA6GD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAOlE;AAgBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAsEvG"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/op/activities/reconcile.ts"],"names":[],"mappings":"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"}

package/dist/op/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/op/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAQL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAIlC,qGAAqG;AACrG,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,oBAAoB,EAAE,CAAC;QAAC,OAAO,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC,CAAC;IACjG,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAYzE;AAED,4HAA4H;AAC5H,wBAAgB,oBAAoB,CAClC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAA;CAAO,GACjF,cAAc,GAAG;IAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAAE,CAgBpD;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mHAAmH;IACnH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GACjB;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,oBAAoB,CAAA;CAAE,GACrD;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAKxE;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAyBlG;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/op/gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAQL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAIlC,qGAAqG;AACrG,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,oBAAoB,EAAE,CAAC;QAAC,OAAO,EAAE,iBAAiB,EAAE,CAAA;KAAE,CAAC,CAAC;IACjG,aAAa,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACpE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAoBzE;AAED,4HAA4H;AAC5H,wBAAgB,oBAAoB,CAClC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAA;CAAO,GACjF,cAAc,GAAG;IAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAA;CAAE,CAgBpD;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mHAAmH;IACnH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GACjB;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,oBAAoB,CAAA;CAAE,GACrD;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC;AAKxE;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,CAyBlG;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/D"}

package/dist/op/local-executor.d.ts

@@ -82,10 +82,25 @@ export interface OpRunResult {
      */
     record: OpRunRecord;
 }
-/** Thrown on terminal Op failure; carries the partial run result for rendering. */
+/**
+ * Thrown on terminal Op failure; carries the partial run result for rendering.
+ *
+ * `cause` is what actually went wrong (#2301). Before it, this class was the
+ * end of the line for any error that was not a `PhaseFailure` — the executor
+ * caught it, built an `OpRunFailure` from the records it had, and never
+ * referenced the error again. Anything thrown outside a step's own
+ * error-capturing path therefore reached the operator as `Op "x" failed` and
+ * nothing else: no error line, no failing step, exit 1. That is how a gate
+ * whose ledger write died on a CI checkout with no `user.email` produced no
+ * text naming git, the ledger, or the identity, on INTENTIUS/choudoufu#1026.
+ */
 export declare class OpRunFailure extends Error {
     readonly result: OpRunResult;
-    constructor(result: OpRunResult);
+    /** The error the run actually died on, when it was not a step's own failure. */
+    readonly cause?: unknown;
+    constructor(result: OpRunResult, options?: {
+        cause?: unknown;
+    });
 }
 /**
  * Find the first `policyGate` step anywhere in the Op (phases + `onFailure`,

package/dist/op/local-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-executor.d.ts","sourceRoot":"","sources":["../../src/op/local-executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"local-executor.d.ts","sourceRoot":"","sources":["../../src/op/local-executor.ts"],"names":[],"mappings":"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"}

package/dist/op/operator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operator.d.ts","sourceRoot":"","sources":["../../src/op/operator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"operator.d.ts","sourceRoot":"","sources":["../../src/op/operator.ts"],"names":[],"mappings":"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"}

package/dist/op/runtimes/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/op/runtimes/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAwCpB;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,iBAAiB,CAoI3F"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/op/runtimes/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAwCpB;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,iBAAiB,CA+I3F"}

package/dist/runtime-adapter.d.ts

@@ -25,9 +25,17 @@ export interface RuntimeAdapter {
      * needs to round-trip content through a shell (`sh -c "echo … | cmd"`) just
      * to feed a command that reads from stdin (e.g. `git hash-object --stdin`).
      */
+    /**
+     * `opts.env` merges over the parent environment rather than replacing it —
+     * a caller pinning `LC_ALL=C` to parse a command's output must not also
+     * have to reconstruct `PATH`, `HOME` and everything else the child needs.
+     * An entry whose value is `""` is passed through as empty, which is how a
+     * gettext override like `LANGUAGE` is neutralised.
+     */
     spawn(cmd: string[], opts?: {
         cwd?: string;
         stdin?: string;
+        env?: Record<string, string>;
     }): Promise<SpawnResult>;
     /** Commands to use when spawning package manager / executor */
     readonly commands: RuntimeCommands;

package/dist/runtime-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-adapter.d.ts","sourceRoot":"","sources":["../src/runtime-adapter.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACpF,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAuDD;;GAEG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAG5C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,cAAc,CAK3C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEvD"}
+{"version":3,"file":"runtime-adapter.d.ts","sourceRoot":"","sources":["../src/runtime-adapter.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD;;;;;OAKG;IACH;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClH,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AA8DD;;GAEG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAG5C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,cAAc,CAK3C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/operator.test.ts

@@ -16,6 +16,7 @@ const readGateResolutionsMock = vi.fn();
 const readGateLedgerMock = vi.fn();
 const readRunLedgerMock = vi.fn();
 const pushLifecycleMock = vi.fn();
+const requireLifecycleLedgerMock = vi.fn();
 
 vi.mock("../../op/operator", async () => {
   const actual = await vi.importActual<typeof import("../../op/operator")>("../../op/operator");
@@ -59,7 +60,13 @@ vi.mock("../../lifecycle/gate-ledger", async () => {
 });
 vi.mock("../../lifecycle/git", async () => {
   const actual = await vi.importActual<typeof import("../../lifecycle/git")>("../../lifecycle/git");
-  return { ...actual, pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args) };
+  return {
+    ...actual,
+    pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+    // Mocked, not merely defaulted: the real one shells to `git fetch`, and
+    // these tests run in the chant checkout itself (#2303).
+    requireLifecycleLedger: (...args: unknown[]) => requireLifecycleLedgerMock(...args),
+  };
 });
 
 // Imported after the mocks above are registered.
@@ -80,6 +87,7 @@ beforeEach(() => {
   loadProfilesMock.mockResolvedValue({});
   discoverOpsMock.mockResolvedValue({ ops: new Map([["fountain-apply", {}]]), errors: [] });
   pushLifecycleMock.mockResolvedValue(true);
+  requireLifecycleLedgerMock.mockResolvedValue(undefined);
   readGateResolutionsMock.mockResolvedValue({ records: [], malformed: 0 });
   readGateLedgerMock.mockResolvedValue({ resolutions: [], pending: [], malformed: 0 });
 });
@@ -726,3 +734,96 @@ describe("runOperatorLog", () => {
     errSpy.mockRestore();
   });
 });
+
+/**
+ * #2303 finding 2, at the handler. The mechanism is proved against real git
+ * in `op/gate.test.ts`; what these hold is that `chant approve` actually goes
+ * through the guard, and stops rather than writing when it refuses — the
+ * append must not be reached, because reaching it is what discarded the
+ * pending fact in the first place.
+ */
+describe("runApprove — the ledger branch is read before it is appended to (#2303)", () => {
+  test("reads the branch before recording the resolution", async () => {
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    expect(await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }))).toBe(0);
+
+    expect(requireLifecycleLedgerMock).toHaveBeenCalled();
+    expect(requireLifecycleLedgerMock.mock.invocationCallOrder[0]).toBeLessThan(
+      appendGateResolutionMock.mock.invocationCallOrder[0],
+    );
+    errSpy.mockRestore();
+  });
+
+  test("refuses by name, and writes nothing, when the branch cannot be read", async () => {
+    requireLifecycleLedgerMock.mockRejectedValue(
+      new Error(
+        'the chant/lifecycle ledger branch is not in this checkout and could not be fetched from "origin"',
+      ),
+    );
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
+
+    expect(code).toBe(1);
+    expect(appendGateResolutionMock).not.toHaveBeenCalled();
+    expect(pushLifecycleMock).not.toHaveBeenCalled();
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toContain("chant/lifecycle ledger branch");
+    errSpy.mockRestore();
+  });
+
+  test("--expire is guarded the same way", async () => {
+    requireLifecycleLedgerMock.mockRejectedValue(new Error("the chant/lifecycle ledger branch has diverged"));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", expire: true }));
+
+    expect(code).toBe(1);
+    expect(appendPendingGateMock).not.toHaveBeenCalled();
+    errSpy.mockRestore();
+  });
+});
+
+/**
+ * #2309 review. `pushLifecycle().catch(() => undefined)` at both write sites
+ * meant a rejected push printed unconditional success and exited 0 — the
+ * operator walks away believing the gate is answered for everybody, while the
+ * resolution exists only in their own checkout.
+ */
+describe("runApprove — a push that does not land is reported (#2309 review)", () => {
+  test("a rejected push warns and marks the success line local-only", async () => {
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    pushLifecycleMock.mockRejectedValue(new Error("Another snapshot completed for chant/lifecycle"));
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    const code = await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
+
+    const out = errSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(out).toMatch(/push to the remote was rejected/);
+    expect(out).toMatch(/local only . the push did not land/);
+    // Still exit 0: the local append is a correct local fact.
+    expect(code).toBe(0);
+    errSpy.mockRestore();
+  });
+
+  test("a project with no remote says nothing was pushed", async () => {
+    appendGateResolutionMock.mockResolvedValue({
+      commit: "sha",
+      record: { version: 1, op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+    });
+    pushLifecycleMock.mockResolvedValue(false);
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+
+    await runApprove(ctx({ path: "fountain-apply", extraPositional: "rollout-gate", actor: "alex" }));
+
+    expect(errSpy.mock.calls.map((c) => String(c[0])).join("\n")).toMatch(/No remote is configured/);
+    errSpy.mockRestore();
+  });
+});