fix(commitrequest): keep a save's writes under its message, and answer it sooner

cmd/main.go

@@ -328,13 +328,18 @@ func main() {
 	fatalIfErr(mgr.Add(watchMgr), "unable to add watch ingestion manager")
 	// CommitRequests created on a source cluster, next to the edits they save: served through every
 	// KubeProvider whose spec.commitRequests reconciles them, attributed from that cluster's audit facts.
+	// A worker's change to a CommitRequest takes the request's next step at once, on either path.
+	commitRequestWakes := controller.NewCommitRequestWakes(workerManager.CommitRequestChanges())
+	fatalIfErr(mgr.Add(commitRequestWakes), "unable to add the CommitRequest wakes")
 	commitRequestServer := &controller.CommitRequestServer{
 		Client:      mgr.GetClient(),
+		APIReader:   mgr.GetAPIReader(),
 		Clusters:    watchMgr,
 		Finalizer:   eventRouter,
 		Authors:     watchMgr.AuthorResolver,
 		FactStreams: watchMgr.FactStreams,
 		TTL:         cfg.commitRequestTTL,
+		Wakes:       commitRequestWakes,
 		Log:         ctrl.Log.WithName("commitrequests"),
 	}
 	fatalIfErr(mgr.Add(commitRequestServer), "unable to add the CommitRequest server")
@@ -423,6 +428,7 @@ func main() {
 		Authors:     watchMgr.AuthorResolver,
 		FactStreams: watchMgr.FactStreams,
 		TTL:         cfg.commitRequestTTL,
+		Wakes:       commitRequestWakes,
 	}).SetupWithManager(mgr); err != nil {
 		setupLog.Error(err, "unable to create controller", "controller", "CommitRequest")
 		os.Exit(1)

docs/TODO.md

@@ -2,22 +2,21 @@
 
 The open work, in one list. Each item is one or two lines with a code pointer or the design page
 that argues it. Ranked within each group, most urgent first. **Before the next release** marks what
-should land before the next tag is cut (the last release is v0.53.0). Checked against `main` at
+should land before the next tag is cut (the last release is v0.55.0). Checked against `main` at
 `1bc97904` on 2026-10-24.
 
 ## Before the next release
 
-Nothing open. The 0.54.0 release PR's changelog was checked against what ships on 2026-10-24.
-
-## Applier claims and bi-directional editing
-
 - [ ] **A withheld apply rides the next edit.** S1 withholds an apply that lands over an edit decided
   after the flush mark, and a `Repair` puts the edit back. But the apply did land on the cluster, so
   the next edit of that object carries the apply's value for every field it did not change, and the
   window commits the whole object under that author's name: the overwritten edit is lost, and the
   `Repair` then applies the loss. The failing test is
   `TestApplyWindow_AWithheldApplyIsNotCommittedUnderTheNextEdit`
   (`internal/git/apply_window_carry_test.go`, skipped; `GITOPS_REVERSER_KNOWN_BUGS=1` runs it).
+
+## Applier claims and bi-directional editing
+
 - [ ] **Reopen the render-fidelity gate after a Git repair, automatically.** Today a target on
   `RenderMatchesLive=False` clears only on an explicit recheck (the
   `reconcile.configbutler.ai/requestedAt` annotation, which restarts every scope; the render

docs/UPGRADING.md

@@ -7,6 +7,36 @@ guidance that the changelog's breaking-change entries link to.
 We are pre-1.0, so breaking changes bump the **minor** version (release-please is configured with
 `bump-minor-pre-major`) rather than the major. Read the relevant entry before upgrading across it.
 
+## A `CommitRequest` reports each phase as the worker reaches it
+
+A request's progress and outcome are written as soon as its branch worker reports them, instead of
+at a two-second poll. Once the worker has registered a request, the poll is only a ten-second
+fallback.
+
+A save's own writes now land in its window. A client that waits for its request to be registered
+before it writes, as `SaveInProgress` asks, used to learn of the registration up to two seconds
+late, which is the whole default `maxDuration`. The window then closed on the earlier writes under
+the save's message, and the save's own writes committed under the generated message, or under the
+next save's message.
+
+`SaveInProgress` is decided when the worker registers the request, after its author was found. A
+client that relies on it to keep two of its saves apart waits for the `Reconciling` reason
+`WaitingForWindow` or `CollectingWindow` before it makes the save's edits, not only for
+`Ready=Unknown`.
+
+## A source-cluster request no path can serve ends `NotAllowed`
+
+A `CommitRequest` on a source cluster whose `GitTarget` mirrors another cluster, either the cluster
+GitOps Reverser runs in or one whose `KubeProvider` serves no `CommitRequest`s, ends `Ready=False`
+with reason `NotAllowed`, naming both clusters. It used to keep no status at all. It finishes, so on
+a `KubeProvider` with `commitRequests: ReconcileAndDeleteFinished` it is deleted after the TTL.
+
+## A save is pushed at once
+
+A push that a `CommitRequest` waits on no longer waits out the five-second push cooldown, as a push
+an apply waits on already did not. Two saves in a row each resolve as soon as their commit is
+pushed. Commits that no save waits on still share one push per cooldown.
+
 ## Upgrading from 0.54.0: drain the `CommitRequest`s first
 
 Existing providers, branches, targets and claims keep running across this upgrade; none of the

docs/api-first-publication.md

@@ -131,6 +131,7 @@ a publication succeeds. These clocks overlap.
 | Retained-byte threshold | Default `8Mi` | Estimated open plus retained bytes reach the threshold | Close the open window under memory pressure |
 | Shutdown | Immediate attempt | The worker exits | Attempt to publish finalized work without waiting for cooldown |
 | Apply due | Immediate | An applier on the branch has an apply due | Close the open window and publish every write decided so far without waiting for cooldown, so the apply includes them |
+| Save | Immediate | A pending write carries a `CommitRequest` | Publish without waiting for cooldown, because a person waits for the save; one save per author at a time keeps this from becoming a burst |
 
 The first publication can push as soon as a commit is ready. There is no initial five-second
 push wait. Setting `commit.window.idleTimeout: 0s` makes local commits immediately; subsequent publications
@@ -282,11 +283,11 @@ are never held by the same worker.
 
 ## Story 3: save now, and know what reached Git
 
-A `CommitRequest` attaches to a matching author-and-target window and closes it. It does not
-bypass the push cooldown. Two settings with separate clocks set the timing: `attachTimeout` runs
-from the worker's registration of the request and bounds the wait for a window, and `maxDuration`
-runs from the attach and bounds the collection that follows. Both default to `2s` and accept `0s`
-to `5m`. A repeat attach restarts neither clock.
+A `CommitRequest` attaches to a matching author-and-target window and closes it. Its commit is
+pushed at once, without waiting for the push cooldown. Two settings with separate clocks set the
+timing: `attachTimeout` runs from the worker's registration of the request and bounds the wait for
+a window, and `maxDuration` runs from the attach and bounds the collection that follows. They
+default to `5s` and `2s` and accept `0s` to `5m`. A repeat attach restarts neither clock.
 
 ```mermaid
 sequenceDiagram

docs/architecture.md

@@ -1553,8 +1553,10 @@ out, the retained buffer reaches `--branch-buffer-max-size` (default `8Mi`), an
 or an apply comes due for an applier on the branch. The timers
 are the GitTarget's `spec.commit.window` until a `CommitRequest` attaches and replaces them. Successful local commits
 are retained until a fixed push cooldown (`5s`) allows a push, which prevents remote push storms during
-bursts. The one exception is an apply's flush: the writes decided before the apply came due are
-pushed at once, cooldown or not, because the apply waits for them.
+bursts. Two things push at once, cooldown or not, because something waits for the push: an apply's
+flush, for the writes decided before the apply came due, and a `CommitRequest`'s commit, for the
+person who saved. Saves cannot burst the way plain writes can, since an author has one save in
+progress at a time, so the cooldown still paces every stream of plain writes.
 
 ### Local clones and conflict retry
 

docs/bi-directional-argocd.md

@@ -430,15 +430,16 @@ applier on the branch, whether or not the push touched its folder, and a `CatchU
 create in the folder and when a `GitTarget` first names the applier claim.
 
 **The apply window.** Until 10 seconds after the sync's operation completes, however long that
-takes, Argo CD's own write to an object nobody edited is the sync landing, and is not mirrored. An
-API edit to a field the `Application` sets, one made after the flush included, can be reverted on
-the cluster by the sync. GitOps Reverser recognizes that write by Argo CD's field manager
-(`argocd-controller`, for a client-side and a server-side apply alike, or
-`argocd-application-controller` for a `Replace=true` sync), withholds it from Git, and asks for a
-`Repair` sync pinned to the tip that holds the edit, but only when Argo CD's entry is as new as the
-edit or newer: undoing an edit can leave an older entry of Argo CD's as the newest, and that undo
-is mirrored. When Argo CD and another manager wrote in the same second, the write is mirrored and
-counted as `ambiguous`.
+takes, and until the watch has delivered every write the cluster held then, for at most two minutes
+([the life of an apply](bi-directional.md#the-life-of-an-apply)), Argo CD's own write to an object
+nobody edited is the sync landing, and is not mirrored. An API edit to a field the `Application`
+sets, one made after the flush included, can be reverted on the cluster by the sync. GitOps Reverser
+recognizes that write by Argo CD's field manager (`argocd-controller`, for a client-side and a
+server-side apply alike, or `argocd-application-controller` for a `Replace=true` sync), withholds it
+from Git, and asks for a `Repair` sync pinned to the tip that holds the edit, but only when Argo
+CD's entry is as new as the edit or newer: undoing an edit can leave an older entry of Argo CD's as
+the newest, and that undo is mirrored. When Argo CD and another manager wrote in the same second,
+the write is mirrored and counted as `ambiguous`.
 
 A request that fails, and a sync that ends `Failed` or `Error`, is decided again from scratch, after
 that `Application`'s own backoff. A sync still running after 5 minutes is `Unresolved`: GitOps

docs/bi-directional-flux.md

@@ -461,11 +461,13 @@ as failed, and records an `OperationUnfollowed` Event. A resumed `Kustomization`
 nothing watching it.
 
 **The apply window.** From the moment an operation is asked for until 10 seconds after it completes,
-a write by `kustomize-controller` alone to an object nobody edited is the apply landing, and is not
-mirrored. A write by `kustomize-controller` over a newer API edit, one made after the flush included,
-is withheld from Git, and GitOps Reverser asks for a `Repair`; the applier claim shows `repairPending`
-until that apply succeeds. Only a `kustomize-controller` entry as new as the edit or newer counts:
-undoing an edit can leave an older one as the newest entry, and that undo is mirrored. When
+and until the watch has delivered every write the cluster held then, for at most two minutes ([the
+life of an apply](bi-directional.md#the-life-of-an-apply)), a write by `kustomize-controller` alone
+to an object nobody edited is the apply landing, and is not mirrored. A write by
+`kustomize-controller` over a newer API edit, one made after the flush included, is withheld from
+Git, and GitOps Reverser asks for a `Repair`; the applier claim shows `repairPending` until that
+apply succeeds. Only a `kustomize-controller` entry as new as the edit or newer counts: undoing an
+edit can leave an older one as the newest entry, and that undo is mirrored. When
 `kustomize-controller` and another manager wrote in the same second, the write is mirrored and
 counted as `ambiguous`.
 

docs/configuration.md

@@ -3023,6 +3023,14 @@ The `GitTarget` a request names decides where it belongs, through the `KubeProvi
   other one's. Create it on the other cluster instead. When that `KubeProvider` does serve them, the
   request is left alone, since the kubeconfig may point back at this cluster and then its own watch
   serves the request. If it points elsewhere, nothing serves the request and it gets no status.
+- **A request on a source cluster, for a `GitTarget` that mirrors another cluster, is refused** with
+  reason `NotAllowed`, and the message names both clusters, when nothing can serve it from there:
+  the `GitTarget` mirrors the cluster GitOps Reverser runs in, or its `KubeProvider` serves no
+  `CommitRequest`s. Create it on the cluster the `GitTarget` mirrors. A refused request finishes,
+  so a `KubeProvider` with `ReconcileAndDeleteFinished` deletes it after the TTL. A kubeconfig that
+  points back at the cluster GitOps Reverser runs in sees that cluster's own requests, and leaves
+  them to it. A request whose `GitTarget`'s `KubeProvider` does serve `CommitRequest`s is left
+  alone, since that `KubeProvider` may connect to the same cluster under another identity.
 
 Only the path the `GitTarget`'s `KubeProvider` picks writes a request's progress, so several
 `KubeProvider`s that watch one cluster never fight over a request. Any of them may report
@@ -3085,12 +3093,13 @@ A request is registered with the branch worker only once its own audit event has
 and its edit is attributed the same way, so a request created just before its edit does not always
 reach the worker first. On a `GitTarget` whose windows close on the first silence (`idleTimeout:
 "0s"`), such an edit can commit alone before the request is there to attach to it. Make the edit
-once the request is claimed (`Ready=Unknown`), or give the `GitTarget` an `idleTimeout` that covers
-the gap.
+once the request is registered, when its `Reconciling` reason is `WaitingForWindow` (see
+[its status](#its-status)), or give the `GitTarget` an `idleTimeout` that covers the gap.
+`Ready=Unknown` alone is too early: it starts at reason `Saving`, before the registration.
 
 `maxDuration`, and `idleTimeout` when set, cover the span of the save's own writes after the
 attach. The worst case from registration to the finalize is `attachTimeout` plus `maxDuration`; the
-push follows, with its cooldown and any retries.
+push follows at once, without the push cooldown, with any retries a remote that refuses it needs.
 
 The two directions are not symmetric. Overshooting costs a few seconds of latency on the commit;
 undershooting `attachTimeout` resolves the request `Ready=True` with reason `NoWindow` while the
@@ -3104,6 +3113,59 @@ request never resolves `NoWindow` while its commit waits out the push cooldown.
 and a request together gives no ordering guarantee between controllers and watch streams. See the
 [request contract](spec/commitrequest-design.md).
 
+#### Saving a folder with `kubectl apply`
+
+To save the objects of a folder in one commit with your message, put a `CommitRequest` in the
+folder, next to them, and give it a new name for every apply:
+
+```yaml
+# save-2026-10-28-checkout-limits.yaml
+apiVersion: configbutler.ai/v1alpha3
+kind: CommitRequest
+metadata:
+  name: save-2026-10-28-checkout-limits
+spec:
+  gitTargetRef:
+    name: example-target
+  message: "feat: raise the checkout limits"
+```
+
+`kubectl apply -f folder/` then commits the folder's changes, authored by you, with the request's
+message. kubectl applies the files in name order, so the request can land before or after the
+objects: with `attach: CurrentOrNext` the request attaches to the window the objects already opened,
+or waits for the one they open. Do not use `attach: Next` here: it would close the objects' window
+under the generated message, then wait for a write that never comes. Another unclaimed edit of yours
+on the same `GitTarget`, still in its window, shares the commit.
+
+It is one commit only when the window holds every write, and a window is not a transaction. Two
+things split it:
+
+- **Time.** With the defaults the window closes 2 seconds after the attach. Writes reach the branch
+  worker once their audit facts have named their author, so on a large folder, a loaded API server or
+  a source cluster with slow audit delivery, the last writes can arrive later than kubectl sent them.
+  A write after the close commits on its own, under the generated message. For such a folder, give
+  the request a longer window, `spec.window.maxDuration: "10s"` for example, or rolling collection
+  (see [the request window](#the-request-window-specwindow)); the commit lands that much later.
+- **Other writes on the branch.** A branch worker holds one window at a time, so a write by another
+  author, or for another `GitTarget` on the same branch, closes yours early, with the request's
+  message, and your later writes commit under the generated message.
+
+The request then ends `Committed` with the writes its window held.
+
+The name is what makes the next apply a save. Applying the same folder again does this:
+
+- **Nothing changed:** kubectl sends no write for an unchanged object, so there is nothing to save,
+  and the finished request keeps its outcome. If the request was already deleted (see
+  [finished requests](#finished-requests-are-deleted-after-48-hours)), the apply creates it again,
+  and it ends `NoWindow`.
+- **Objects changed, same request:** the request is unchanged and finished, so it saves nothing.
+  The edits commit on the `GitTarget`'s own timers, under the generated message.
+- **Message edited, same name:** the API server refuses the request, because its spec is
+  immutable, and kubectl exits with an error after applying the other files. Their edits commit
+  under the generated message.
+
+The request itself is never mirrored, even when a `WatchRule` covers its folder or its type.
+
 ### Who may save: `spec.allowedCommitRequests`
 
 A `GitTarget` says which `CommitRequest`s may save its windows in `spec.allowedCommitRequests`, a
@@ -3237,8 +3299,15 @@ request produced a pushed commit:
   message, so the two would race for it and one message would be lost without a word; the later
   request is refused at once instead. Save again with a new request once the earlier one is `Ready`.
   A request for the `Next` window is not refused by one that is collecting: it closes that window
-  under the earlier request's message first. Saves by different authors never race, since each
-  author has windows of its own.
+  under the earlier request's message first. Saves by different authors do not race for a
+  message: a write by another author closes the open window, and its message, before it opens one
+  of its own.
+
+  `SaveInProgress` is decided when the branch worker registers the request, which is after its
+  author was found, not when it is created. A client that relies on it to keep two of its saves
+  apart waits until the `Reconciling` reason is `WaitingForWindow` or `CollectingWindow` before it
+  makes the save's edits, not only for `Ready=Unknown`: a request still `Saving` is not registered
+  yet, and its edits could reach the window of the save before it.
 
   `AlreadyPresent` means **the remote confirmed there was nothing to add**, so it is reported after
   the push rather than when the local plan found no difference. That costs a few seconds and buys a
@@ -3248,7 +3317,8 @@ request produced a pushed commit:
 - **Reconciling** / **Stalled**: the kstatus progress/blocked pair. `Reconciling=True` while the
   request is in progress, with the phase the branch worker reports as its reason: `Saving`
   (claimed, not yet registered), `WaitingForWorker` (the GitTarget has no branch worker yet),
-  `WaitingForWindow`, `CollectingWindow`, or `WaitingForPush`.
+  `WaitingForWindow`, `CollectingWindow`, or `WaitingForPush`. Each phase, and the outcome, is
+  written as soon as the branch worker reports it.
   `Stalled=True` when the request failed and needs attention (kstatus reports the object Failed).
 - **Pushed**: `True` once the commit, empty or not, is in the remote repository.
 - **Applied**: only with [`catchUp: AfterPush`](#applying-a-save-at-once), once `Ready=True`: