From d4a9eb798695010b4f6f4a7dd4ddcde3939c97c2 Mon Sep 17 00:00:00 2001
From: Jacob Stephens <jstephens@etadventures.com>
Date: Tue, 10 Nov 2026 22:47:17 -0500
Subject: [PATCH 1/8] Wait out GitHub quota exhaustion in running Commands
 (#1997)

---
 docs/guide.md                 |   8 +
 site/docs/index.html          |   4 +
 site/how-it-works/index.html  |   1 +
 src/github.rs                 |  30 +++-
 src/github/check_read.rs      |   2 +
 src/github/execution_tests.rs |   6 +-
 src/github/quota.rs           |  76 +++++----
 src/github/quota/command.rs   | 153 ++++++++++++++++++
 src/github/quota/wait.rs      |  24 ++-
 src/logs.rs                   |  20 +++
 src/logs/command_record.rs    |   3 +
 src/logs/reading.rs           |  27 +++-
 src/logs/reading/health.rs    |   6 +-
 src/logs/reading/tests.rs     |  33 ++++
 src/logs/recording.rs         |   7 +
 src/logs/recording/tests.rs   |  29 ++++
 src/notification.rs           |   7 +
 tests/console.rs              |  24 +++
 tests/quota_wait.rs           | 292 ++++++++++++++++++++++++++++++++++
 19 files changed, 702 insertions(+), 50 deletions(-)
 create mode 100644 src/github/quota/command.rs
 create mode 100644 tests/quota_wait.rs

diff --git a/docs/guide.md b/docs/guide.md
index e3824b73d..76a3c5797 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -45,6 +45,8 @@ From a clone of the issue's repository, `thirdshift <Issue URL>`:
 7. In a **Ticket run** that Self-merges (`thirdshift merge <Issue URL>`), does the **Self-merge**: once the pull request is open, ready for review, mergeable and green, thirdshift merges it into the Base branch with a merge commit, on exactly the head commit whose CI it watched (`gh pr merge --merge --match-head-commit <sha>`). Just before each attempt, it reads the PR's `reviewDecision`: `REVIEW_REQUIRED` or `CHANGES_REQUESTED` ends the Ticket run as **review required**, a policy refusal, without attempting the merge or taking another Repair round. An empty or `APPROVED` decision, or a failed read, keeps the existing merge behavior. It never uses GitHub's auto-merge ([ADR-0004](adr/0004-self-merge-by-thirdshift-not-github-auto-merge.md)). A merge that fails goes back round step 6, within the same budgets, and is tried again on the new green head. If that round finds nothing to fix, the refusal is a **policy refusal**, such as merge commits being disallowed or a review being required. After the merge, thirdshift deletes the Issue branch on `origin`, and closes the issue if it is still open, with the comment `Closed by #<pr>, merged into <base> by a thirdshift Ticket run with Self-merge.` GitHub closes it on its own only for a merge into the repository's default branch, and then thirdshift leaves it alone. Once the issue is closed, either way, thirdshift takes `in-progress` off it, [removing the Claim](#when-the-claim-ends).
 8. Cleans up: removes the worktree, the local Issue branch and the temporary directory the Factory skills were written out to, whether the Ticket run succeeded or not. The one exception is a **Failed ticket run** whose work could not be pushed: see below.
 
+CI watch quota exhaustion follows the [Command's Quota wait policy](#delivery-and-pull-request-identity): reset plus one minute and 0–60 seconds of jitter, within a shared two-hour cap. Secondary limits retry after 60 seconds, at most five times. Neither is a CI failure or a reason to start a Repair while retries remain.
+
 ### Worktree ownership and cleanup
 
 A factory-owned checkout, on an **Issue branch** for a **Ticket run** or detached for an **Architecture review**.
@@ -63,6 +65,10 @@ See [ADR-0014](adr/0014-successful-review-acquisition-authorizes-stale-disposal.
 
 What a **Ticket run**, or a **Spec run** for its **Spec PR**, does from its worktree once its work begins. It runs the opening session (the implement session, or the **Spec review**), pushes, marks the pull request ready, keeps it mergeable and green through the **Repair loop**, and, in a **Ticket run** that Self-merges, does the **Self-merge**.
 
+When thirdshift's own GitHub reads or writes hit primary quota exhaustion, the running **Command** records a **Quota wait**, waits until reset plus one minute and a random 0–60 seconds, then retries the same call. This includes CI watch and Delivery's pull request updates, labels, comments and Self-merge, across Ticket, Spec, Review, Fix, Security and Triage runs, Custom processes and work a Pass dispatched. The Command and its child Ticket runs share a two-hour total wait cap; a call that would exceed it fails as before. A secondary-limit failure instead waits 60 seconds and retries up to five times, without recording a Quota wait.
+
+While waiting, `status`, `show` and the Console show `Quota wait until <time>` as the stage; afterwards the previous stage resumes. Slow timing includes the wait. Stop or another interruption ends an ordinary wait immediately. Claim ending, Failed ticket run salvage, confirmed Self-merge completion and Spec accounting still wait within the cap after interruption. A Quota wait itself is no failure and adds no `agent-failed` label. Agent sessions' own `gh` calls keep their existing behavior.
+
 For a Spec PR, Delivery ends Ticket accounting's capture before the Spec review, allowing that session to replace the PR. The first successful observation after the opening session, or during Failed ticket run completion after an opening failure, captures one pull request number and URL in the issue's repository; all later observations and transitions use that identity. Readiness and every mergeability poll validate its expected **Issue branch** and **Base branch**, open state and readiness where required. A missing, closed or retargeted captured PR fails Delivery; a replacement from the same branch is never substituted.
 
 A Delivery that fails takes the **Failed ticket run** path, drafting that same captured open PR after preserving work. Spec PR checklist restoration uses that Delivery capture before readiness and for final accounting after failure.
@@ -2861,6 +2867,8 @@ Setup validates the Credentials before asking questions on a terminal. For email
 
 #### Run notifications
 
+A Command that waited for primary GitHub quota includes one line, `Waited <duration> for the GitHub quota (<resource>)`, totaling its waits and its child Ticket runs' waits. A Command that never waited has no such line; secondary-limit retries add none.
+
 `--email` (or `email`) asks a Ticket run for a **Run notification**: one email, sent when the Ticket run ends, whatever the outcome. The word after the flag is the address only if it contains `@` and doesn't start with `https://`, so the Issue URL is never taken for it; otherwise the email goes to the matching `email.to_by_repo` entry, falling back to `email.to`. With `email.always = true` in the [User config](#user-config), a Ticket run asks for one without the flag, and `--no-email` (or `no-email`) skips it for that Ticket run; an address after `--email` still wins over both configured recipients. Giving a flag twice, or any two of `--email`, `--email-unless-merged` and `--no-email`, is an argument error.
 
 `--email-unless-merged` (or `email-unless-merged`), optionally followed by an address as `--email` is, asks for a Run notification that is emailed only when the command did not end `merged`, whatever else it ended as. A merged one is still saved beside the [Command log](#logs), with nothing sent, unless it is a [Security run](#security-runs) whose fix left its finding open or whose audit left findings waiting for the Day shift: that one is emailed. It makes the same checks as `--email` before any work.
diff --git a/site/docs/index.html b/site/docs/index.html
index 4a311db0f..87a45dd90 100644
--- a/site/docs/index.html
+++ b/site/docs/index.html
@@ -102,6 +102,7 @@
 <li><p>Cleans up: removes the worktree, the local Issue branch and the temporary directory the Factory skills were written out to, whether the Ticket run succeeded or not. The one exception is a <strong>Failed ticket run</strong> whose work could not be pushed: see below.</p>
 </li>
 </ol>
+<p>CI watch quota exhaustion follows the <a href="#delivery-and-pull-request-identity">Command&#39;s Quota wait policy</a>: reset plus one minute and 0–60 seconds of jitter, within a shared two-hour cap. Secondary limits retry after 60 seconds, at most five times. Neither is a CI failure or a reason to start a Repair while retries remain.</p>
 <details class="fold"><summary><h3>Worktree ownership and cleanup</h3></summary>
 <div class="manual-content" id="worktree-ownership-and-cleanup">
 <p>A factory-owned checkout, on an <strong>Issue branch</strong> for a <strong>Ticket run</strong> or detached for an <strong>Architecture review</strong>.</p>
@@ -114,6 +115,8 @@
 <details class="fold"><summary><h3>Delivery and pull request identity</h3></summary>
 <div class="manual-content" id="delivery-and-pull-request-identity">
 <p>What a <strong>Ticket run</strong>, or a <strong>Spec run</strong> for its <strong>Spec PR</strong>, does from its worktree once its work begins. It runs the opening session (the implement session, or the <strong>Spec review</strong>), pushes, marks the pull request ready, keeps it mergeable and green through the <strong>Repair loop</strong>, and, in a <strong>Ticket run</strong> that Self-merges, does the <strong>Self-merge</strong>.</p>
+<p>When thirdshift&#39;s own GitHub reads or writes hit primary quota exhaustion, the running <strong>Command</strong> records a <strong>Quota wait</strong>, waits until reset plus one minute and a random 0–60 seconds, then retries the same call. This includes CI watch and Delivery&#39;s pull request updates, labels, comments and Self-merge, across Ticket, Spec, Review, Fix, Security and Triage runs, Custom processes and work a Pass dispatched. The Command and its child Ticket runs share a two-hour total wait cap; a call that would exceed it fails as before. A secondary-limit failure instead waits 60 seconds and retries up to five times, without recording a Quota wait.</p>
+<p>While waiting, <code>status</code>, <code>show</code> and the Console show <code>Quota wait until &lt;time&gt;</code> as the stage; afterwards the previous stage resumes. Slow timing includes the wait. Stop or another interruption ends an ordinary wait immediately. Claim ending, Failed ticket run salvage, confirmed Self-merge completion and Spec accounting still wait within the cap after interruption. A Quota wait itself is no failure and adds no <code>agent-failed</code> label. Agent sessions&#39; own <code>gh</code> calls keep their existing behavior.</p>
 <p>For a Spec PR, Delivery ends Ticket accounting&#39;s capture before the Spec review, allowing that session to replace the PR. The first successful observation after the opening session, or during Failed ticket run completion after an opening failure, captures one pull request number and URL in the issue&#39;s repository; all later observations and transitions use that identity. Readiness and every mergeability poll validate its expected <strong>Issue branch</strong> and <strong>Base branch</strong>, open state and readiness where required. A missing, closed or retargeted captured PR fails Delivery; a replacement from the same branch is never substituted.</p>
 <p>A Delivery that fails takes the <strong>Failed ticket run</strong> path, drafting that same captured open PR after preserving work. Spec PR checklist restoration uses that Delivery capture before readiness and for final accounting after failure.</p>
 <p>If a Delivery gate observes that its pull request has already merged into the expected Base branch, and its merged head includes all local work (the exact local head, with no uncommitted changes), the Ticket run ends as merged, even when it originally asked only for ready for review. Delivery stops further publication, PR edits and Self-merge work. A merged PR that leaves local work out still fails and retains that work; a merged state alone never establishes completion.</p>
@@ -2824,6 +2827,7 @@
 <p>Setup validates the Credentials before asking questions on a terminal. For email, <code>email-test</code>, the Console and a Run or a Pass that asks for a notification read them only when <code>RESEND_API_KEY</code> is unset or empty. A missing file just means no key from it. The file accepts quoted <code>resend.key</code>, <code>claude.setup_token</code> and <code>opencode.api_key</code> values, and an <code>[opencode.keys]</code> table of quoted keys by OpenCode provider name. Invalid TOML, unknown sections or keys (such as <code>kye</code>), and values of other types stop the command with exit <code>1</code>, naming the file and the offending key, and nothing is sent. An OpenCode Trial&#39;s provider key goes there by hand until <code>setup</code> asks for it: one per provider under <code>[opencode.keys]</code>, such as <code>fireworks-ai = &quot;…&quot;</code> and <code>baseten = &quot;…&quot;</code>, or a single <code>api_key</code> under <code>[opencode]</code> for any provider without its own. Each OpenCode session takes the key for the provider its Model names, so two OpenCode sessions on different providers, such as two Graders in a Grader panel, each get their own; without one, an OpenCode Trial fails before its session starts. A Grok Trial signs its own Trials home in once, with <code>GROK_HOME=~/.thirdshift/trials/grok grok login</code>; without that login, a Grok Trial fails before its session starts. One that others can read is still used, with a <code>warning:</code> line on stderr saying to <code>chmod 600</code> it. Nothing is sent to check the key itself. When Resend accepts the email, it prints <code>accepted by Resend; check your inbox</code> and exits <code>0</code>; that is all it can verify, so check that the email arrives. When Resend refuses it, for example for a bad key or a sender it won&#39;t send from, it prints Resend&#39;s error text word for word, with where the key came from, and exits <code>1</code>. It gives up after 30 seconds without an answer.</p>
 <details class="fold"><summary><h4>Run notifications</h4></summary>
 <div class="manual-content" id="run-notifications">
+<p>A Command that waited for primary GitHub quota includes one line, <code>Waited &lt;duration&gt; for the GitHub quota (&lt;resource&gt;)</code>, totaling its waits and its child Ticket runs&#39; waits. A Command that never waited has no such line; secondary-limit retries add none.</p>
 <p><code>--email</code> (or <code>email</code>) asks a Ticket run for a <strong>Run notification</strong>: one email, sent when the Ticket run ends, whatever the outcome. The word after the flag is the address only if it contains <code>@</code> and doesn&#39;t start with <code>https://</code>, so the Issue URL is never taken for it; otherwise the email goes to the matching <code>email.to_by_repo</code> entry, falling back to <code>email.to</code>. With <code>email.always = true</code> in the <a href="#user-config">User config</a>, a Ticket run asks for one without the flag, and <code>--no-email</code> (or <code>no-email</code>) skips it for that Ticket run; an address after <code>--email</code> still wins over both configured recipients. Giving a flag twice, or any two of <code>--email</code>, <code>--email-unless-merged</code> and <code>--no-email</code>, is an argument error.</p>
 <p><code>--email-unless-merged</code> (or <code>email-unless-merged</code>), optionally followed by an address as <code>--email</code> is, asks for a Run notification that is emailed only when the command did not end <code>merged</code>, whatever else it ended as. A merged one is still saved beside the <a href="#logs">Command log</a>, with nothing sent, unless it is a <a href="#security-runs">Security run</a> whose fix left its finding open or whose audit left findings waiting for the Day shift: that one is emailed. It makes the same checks as <code>--email</code> before any work.</p>
 <p>A Ticket run that asks for a notification, by either flag or by <code>email.always</code> or <code>email.unless_merged</code>, makes the same checks as <code>email-test</code> before any other work: an address is known, and a key is found, in <code>RESEND_API_KEY</code> or else the Credentials. If either fails, or the Credentials are broken, the Ticket run stops, exits <code>1</code> naming what&#39;s wrong (with no key, the message above listing every way to give one), and sends nothing. A Ticket run that asks for no notification never reads the Credentials, so a broken file can&#39;t stop it, and <code>update</code>, <code>version</code> and <code>help</code> never read it either. Once they pass, every way the Ticket run ends sends exactly one notification, after its outcome is final and its cleanup done: ready for review, merged, a <a href="#failed-ticket-runs">Failed ticket run</a> (including a later preflight failure such as an origin mismatch), or interrupted by Ctrl-C, SIGTERM or a closed terminal.</p>
diff --git a/site/how-it-works/index.html b/site/how-it-works/index.html
index 9f3c4b242..a16adf804 100644
--- a/site/how-it-works/index.html
+++ b/site/how-it-works/index.html
@@ -124,6 +124,7 @@ <h1>How thirdshift works</h1>
     <details class="wrap guide-section fold">
       <summary class="sec-head"><p class="eyebrow">04 / From a published change to a checked result</p><h2 id="delivery-title">Deliver against the latest Base branch</h2></summary>
       <div class="guide-content" id="delivery">
+      <p>A running Command whose own GitHub call hits primary quota exhaustion waits until reset plus one minute and a random 0–60 seconds, then retries. CI watch and Delivery share a two-hour total cap with child Ticket runs. A secondary limit gets up to five retries, 60 seconds apart. During a primary wait, <code>status</code>, <code>show</code> and the Console show <code>Quota wait until &lt;time&gt;</code>; Slow timing includes the wait. Stop interrupts ordinary waits; Claim ending and other completion work still finish within the cap. The Run notification totals primary waits in one <code>Waited &lt;duration&gt; for the GitHub quota (&lt;resource&gt;)</code> line. Waiting itself adds no <code>agent-failed</code>; agent sessions' own <code>gh</code> calls are unchanged.</p>
       <p>A pull request existing is not the finish line. <strong>Delivery</strong> runs the opening session, then keeps the captured pull request mergeable and checks CI. This orchestration is thirdshift's code; a <strong>Repair</strong> is another agent session started when the branch needs work.</p>
       <p>For an existing open pull request, <code>thirdshift fix &lt;PR URL or number&gt;</code> starts a <a href="/docs/#fix-runs">Fix run</a> directly at Delivery. Ready and draft PRs by Trusted accounts are accepted, with or without closing issues. It uses the PR's own Base branch, reserves the PR while running and gives each Repair trusted PR and linked-issue context. The usual merge, Base fix, Harness and email defaults apply; failure preserves work and offers <code>thirdshift fix</code> again.</p>
       <p>With no PR target, <code>thirdshift fix [base &lt;branch&gt;] [--author &lt;login&gt;]</code> is a Pass. Without <code>--author</code>, it first checks the Base branch's origin tip: a failed first push attempt gets one failed-jobs re-run and a skip while it runs. Persistent or non-rerunnable failures get a CI-fix session on <code>fix-&lt;base&gt;-&lt;short-sha&gt;</code> and a repair PR targeting the Base branch, treating every red check as its own. Existing PRs from that branch prevent duplicates, failed drafts included. Merge and email policy apply, and Self-merge closes the Base branch's CI-red reports and Base fix issues.</p>
diff --git a/src/github.rs b/src/github.rs
index 77c502772..9aea560b8 100644
--- a/src/github.rs
+++ b/src/github.rs
@@ -1276,13 +1276,31 @@ impl GitHub {
     }
 
     fn output_with_input(&self, args: &[&str], input: Option<&[u8]>) -> Result<Output> {
-        let output = self.raw_output_with_input(args, input)?;
-        if !output.status.success() && self.record_quota_failure(args, &output.stderr).is_err() {
-            // The original failure remains the caller's error, even when the
-            // machine cannot persist its wait or identify its signed-in user.
-            eprintln!("thirdshift: could not record GitHub Quota wait");
+        let mut secondary_retries = 0;
+        loop {
+            let output = self.raw_output_with_input(args, input)?;
+            if output.status.success() {
+                return Ok(output);
+            }
+            match quota::Limit::of(args, &output.stderr) {
+                Some(quota::Limit::Primary(resource)) => {
+                    let reset = self.record_quota_failure(args, resource);
+                    if !quota::command::wait(reset, resource, self.interruption)? {
+                        return Ok(output);
+                    }
+                }
+                Some(quota::Limit::Secondary)
+                    if quota::command::active() && secondary_retries < 5 =>
+                {
+                    secondary_retries += 1;
+                    crate::progress::step(format!(
+                        "GitHub secondary limit; retry {secondary_retries}/5 in 60s"
+                    ));
+                    self.interruption.pause(quota::wait::minute())?;
+                }
+                _ => return Ok(output),
+            }
         }
-        Ok(output)
     }
 
     fn raw_output_with_input(&self, args: &[&str], input: Option<&[u8]>) -> Result<Output> {
diff --git a/src/github/check_read.rs b/src/github/check_read.rs
index 460750c02..ae32c9b1f 100644
--- a/src/github/check_read.rs
+++ b/src/github/check_read.rs
@@ -46,6 +46,8 @@ pub(crate) fn is_transient(error: &anyhow::Error) -> bool {
     // Quota exhaustion belongs to quota-aware deferral, not a short retry.
     // gh can report GraphQL quota errors with or without an HTTP status.
     if stderr.contains("api rate limit")
+        || stderr.contains("secondary rate limit")
+        || stderr.contains("abuse detection")
         || stderr.contains("rate_limited")
         || stderr.contains("rate_limit_exceeded")
     {
diff --git a/src/github/execution_tests.rs b/src/github/execution_tests.rs
index 3e65acc76..bac7b8936 100644
--- a/src/github/execution_tests.rs
+++ b/src/github/execution_tests.rs
@@ -614,9 +614,9 @@ printf '%s' '{{"title":"Recovered"}}'
 }
 
 #[test]
-fn permanent_and_quota_read_failures_are_not_retried() {
+fn permanent_reads_and_quota_reads_outside_a_command_are_not_retried() {
     with_recorded_signal(
-        "github::execution_tests::permanent_and_quota_read_failures_are_not_retried",
+        "github::execution_tests::permanent_reads_and_quota_reads_outside_a_command_are_not_retried",
         |_| {
             let fixture = Fixture::new("");
             for stderr in [
@@ -1620,7 +1620,7 @@ fn check_reads_classify_transport_and_api_failures_without_hiding_diagnostics()
                 ("read tcp: connection reset by peer", true),
                 ("net/http: TLS handshake timeout", true),
                 ("gh: too many requests (HTTP 429)", true),
-                ("GraphQL: secondary rate limit exceeded (HTTP 429)", true),
+                ("GraphQL: secondary rate limit exceeded (HTTP 429)", false),
                 ("gh: Bad Gateway (HTTP 502)", true),
                 ("gh: service unavailable (HTTP 503)", true),
                 ("gh: Gateway Timeout (HTTP 504)", true),
diff --git a/src/github/quota.rs b/src/github/quota.rs
index 87437e8dc..40dae1e1f 100644
--- a/src/github/quota.rs
+++ b/src/github/quota.rs
@@ -1,5 +1,4 @@
-//! Shared machine-local Quota waits. Observing a wait does not yet change how
-//! Passes or running Commands execute.
+//! Shared machine-local Quota waits and running Command recovery.
 use anyhow::{Context, Result};
 use chrono::{DateTime, SecondsFormat, Utc};
 use serde::{Deserialize, Serialize};
@@ -7,15 +6,11 @@ use serde_json::Value;
 
 use super::GitHub;
 
+pub(crate) mod command;
 mod identity;
 mod store;
 #[cfg(test)]
 mod tests;
-// The wait planner is the seam the following Command-wait Ticket consumes.
-#[expect(
-    dead_code,
-    reason = "wait planning is connected to Commands by a later Ticket"
-)]
 pub(crate) mod wait;
 
 pub(crate) use store::QuotaWait;
@@ -151,29 +146,8 @@ impl GitHub {
         self.quota_waits()
     }
 
-    pub(super) fn record_quota_failure(&self, args: &[&str], stderr: &[u8]) -> Result<()> {
-        let diagnostic = String::from_utf8_lossy(stderr).to_ascii_lowercase();
-        if diagnostic.contains("secondary rate limit")
-            || !(diagnostic.contains("api rate limit exceeded")
-                || diagnostic.contains("api rate limit already exceeded")
-                || diagnostic.contains("rate_limit_exceeded")
-                || diagnostic.contains("rate_limited"))
-        {
-            return Ok(());
-        }
-        let resource = if diagnostic.contains("graphql:")
-            || args.starts_with(&["api", "graphql"])
-            || args.first() != Some(&"api")
-                && (diagnostic.contains("rate_limit_exceeded")
-                    || diagnostic.contains("rate_limited"))
-        {
-            Resource::Graphql
-        } else {
-            Resource::Core
-        };
+    pub(super) fn record_quota_failure(&self, args: &[&str], resource: Resource) -> DateTime<Utc> {
         let host = identity::host(args);
-        let store = Store::machine()?;
-        let account = identity::resolve(self, &store, &host)?;
         let now = Utc::now();
         let resource_json = self
             .quota_json(&["api", "rate_limit", "--hostname", &host])
@@ -186,6 +160,48 @@ impl GitHub {
                 .and_then(|reset| DateTime::from_timestamp(reset, 0))
                 .unwrap_or(now + chrono::Duration::minutes(15)),
         };
-        store.exhausted(&account, resource, quota, now)
+        let reset = quota.reset_at;
+        let record = || -> Result<()> {
+            let store = Store::machine()?;
+            let account = identity::resolve(self, &store, &host)?;
+            store.exhausted(&account, resource, quota, now)
+        };
+        if record().is_err() {
+            // Recording failure must not prevent waiting or hide the original
+            // GitHub diagnostic if the Command reaches its wait cap.
+            crate::progress::step("warning: could not record GitHub Quota wait");
+        }
+        reset
+    }
+}
+
+pub(super) enum Limit {
+    Primary(Resource),
+    Secondary,
+}
+
+impl Limit {
+    pub(super) fn of(args: &[&str], stderr: &[u8]) -> Option<Self> {
+        let diagnostic = String::from_utf8_lossy(stderr).to_ascii_lowercase();
+        if diagnostic.contains("secondary rate limit") || diagnostic.contains("abuse detection") {
+            return Some(Self::Secondary);
+        }
+        if !(diagnostic.contains("api rate limit exceeded")
+            || diagnostic.contains("api rate limit already exceeded")
+            || diagnostic.contains("rate_limit_exceeded")
+            || diagnostic.contains("rate_limited"))
+        {
+            return None;
+        }
+        let graphql = diagnostic.contains("graphql:")
+            || args.starts_with(&["api", "graphql"])
+            || args.first() != Some(&"api")
+                && (diagnostic.contains("rate_limit_exceeded")
+                    || diagnostic.contains("rate_limited"));
+        Some(Self::Primary(if graphql {
+            Resource::Graphql
+        } else {
+            Resource::Core
+        }))
     }
 }
diff --git a/src/github/quota/command.rs b/src/github/quota/command.rs
new file mode 100644
index 000000000..74515c94a
--- /dev/null
+++ b/src/github/quota/command.rs
@@ -0,0 +1,153 @@
+//! One budget and notification total per owning Command, including subprocess
+//! Ticket runs. The Command log owner supplies their shared sidecar path.
+use std::collections::BTreeSet;
+use std::fs::{self, OpenOptions};
+use std::io::Write;
+use std::path::PathBuf;
+use std::sync::Mutex;
+use std::time::{Duration, Instant};
+
+use anyhow::Result;
+use chrono::{DateTime, SecondsFormat, Utc};
+use serde::{Deserialize, Serialize};
+
+use super::{Resource, wait::WaitBudget};
+use crate::{logs, process::Interruption, progress};
+
+#[derive(Clone, Default, Serialize, Deserialize)]
+struct Totals {
+    budget: WaitBudget,
+    waited: Duration,
+    resources: BTreeSet<String>,
+}
+
+#[derive(Default)]
+struct Command {
+    totals: Totals,
+    path: Option<PathBuf>,
+}
+
+static COMMAND: Mutex<Option<Command>> = Mutex::new(None);
+
+pub(crate) fn begin() {
+    COMMAND.lock().unwrap().get_or_insert_with(Command::default);
+}
+
+pub(in crate::github) fn active() -> bool {
+    COMMAND.lock().unwrap().is_some()
+}
+
+/// Called outside the recording lock, once its owner is known. A child uses
+/// the inherited outermost owner, never its own child record's path.
+pub(crate) fn attach(path: PathBuf) -> Result<()> {
+    let mut command = COMMAND.lock().unwrap();
+    let Some(command) = command.as_mut() else {
+        return Ok(());
+    };
+    if command.path.is_none() {
+        let totals = std::mem::take(&mut command.totals);
+        command.path = Some(path.with_extension("quota-wait.json"));
+        // Before log allocation, only the parent can have waited. Commands
+        // that never wait need no quota sidecar.
+        if !totals.waited.is_zero() {
+            command.update(|stored| *stored = totals)?;
+        }
+    }
+    Ok(())
+}
+
+impl Command {
+    fn read(&self) -> Result<Totals> {
+        let Some(path) = &self.path else {
+            return Ok(self.totals.clone());
+        };
+        match fs::read(path) {
+            Ok(bytes) => Ok(serde_json::from_slice(&bytes)?),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(Totals::default()),
+            Err(error) => Err(error.into()),
+        }
+    }
+
+    fn update<T>(&mut self, change: impl FnOnce(&mut Totals) -> T) -> Result<T> {
+        let Some(path) = &self.path else {
+            return Ok(change(&mut self.totals));
+        };
+        let lock = OpenOptions::new()
+            .create(true)
+            .truncate(false)
+            .write(true)
+            .open(path.with_extension("lock"))?;
+        lock.lock()?;
+        let mut totals = self.read()?;
+        let value = change(&mut totals);
+        let mut tmp = tempfile::NamedTempFile::new_in(path.parent().unwrap())?;
+        tmp.write_all(&serde_json::to_vec(&totals)?)?;
+        tmp.persist(path)?;
+        Ok(value)
+    }
+}
+
+/// The ordinary sleep and the completion sleep share accounting but preserve
+/// their caller's interruption policy. A rejected reservation leaves the
+/// caller's original GitHub failure intact.
+pub(in crate::github) fn wait(
+    reset: DateTime<Utc>,
+    resource: Resource,
+    interruption: Interruption,
+) -> Result<bool> {
+    let delay = {
+        let mut command = COMMAND.lock().unwrap();
+        let Some(command) = command.as_mut() else {
+            return Ok(false);
+        };
+        command.update(|totals| totals.budget.next(reset.max(Utc::now())))?
+    };
+    let Ok(delay) = delay else { return Ok(false) };
+    let until = (Utc::now() + chrono::Duration::from_std(delay)?)
+        .to_rfc3339_opts(SecondsFormat::Secs, true);
+    logs::quota_wait(Some(&until));
+    let started = Instant::now();
+    let mut left = delay;
+    let result = loop {
+        progress::step(format!("Quota wait until {until} ({})", resource.name()));
+        if let Err(error) = interruption.pause(left.min(Duration::from_secs(30))) {
+            break Err(error);
+        }
+        left = delay.saturating_sub(started.elapsed());
+        if left.is_zero() {
+            break Ok(());
+        }
+    };
+    logs::quota_wait(None);
+    let elapsed = started.elapsed().min(delay);
+    if let Some(command) = COMMAND.lock().unwrap().as_mut() {
+        command.update(|totals| {
+            totals.budget.refund(delay.saturating_sub(elapsed));
+            totals.waited += elapsed;
+            if !elapsed.is_zero() {
+                totals.resources.insert(resource.name().into());
+            }
+        })?;
+    }
+    result.map(|()| true)
+}
+
+pub(crate) fn notification_line() -> Result<Option<String>> {
+    let command = COMMAND.lock().unwrap();
+    let Some(command) = command.as_ref() else {
+        return Ok(None);
+    };
+    let totals = command.read()?;
+    Ok((!totals.waited.is_zero()).then(|| {
+        format!(
+            "Waited {} for the GitHub quota ({})",
+            progress::duration(totals.waited),
+            totals
+                .resources
+                .iter()
+                .cloned()
+                .collect::<Vec<_>>()
+                .join(", ")
+        )
+    }))
+}
diff --git a/src/github/quota/wait.rs b/src/github/quota/wait.rs
index 4cbed3773..fa1dfbe2c 100644
--- a/src/github/quota/wait.rs
+++ b/src/github/quota/wait.rs
@@ -1,11 +1,11 @@
-//! Wait planning only; later Tickets connect this to running Commands.
+//! A running Command's primary-quota wait budget, shared by its child Runs.
 use std::time::Duration;
 
 use chrono::{DateTime, Utc};
 
 const COMMAND_CAP: Duration = Duration::from_secs(2 * 60 * 60);
 
-#[derive(Default)]
+#[derive(Clone, Default, serde::Serialize, serde::Deserialize)]
 pub(crate) struct WaitBudget {
     total: Duration,
 }
@@ -28,7 +28,11 @@ impl WaitBudget {
     ) -> Result<Duration, WaitCapExceeded> {
         let jitter = jitter_seconds();
         assert!(jitter <= 60, "Quota wait jitter must be in 0..=60 seconds");
-        let until = reset + chrono::Duration::seconds(60 + jitter as i64);
+        // The override shortens the safety minute and jitter for binary tests;
+        // the reset itself remains a real wall-clock deadline.
+        let minute = minute();
+        let margin = minute + minute.mul_f64(jitter as f64 / 60.0);
+        let until = reset + chrono::Duration::from_std(margin).unwrap();
         let wait = (until - clock()).to_std().unwrap_or(Duration::ZERO);
         let total = self.total.checked_add(wait).ok_or(WaitCapExceeded)?;
         if total > COMMAND_CAP {
@@ -37,4 +41,18 @@ impl WaitBudget {
         self.total = total;
         Ok(wait)
     }
+
+    pub(super) fn refund(&mut self, unused: Duration) {
+        self.total = self.total.saturating_sub(unused);
+    }
+}
+
+/// Shorten a quota safety minute for binary tests, as with CI's grace period.
+pub(in crate::github) fn minute() -> Duration {
+    std::env::var("THIRDSHIFT_QUOTA_MINUTE_MS")
+        .ok()
+        .and_then(|ms| ms.parse().ok())
+        .filter(|ms| *ms > 0)
+        .map(Duration::from_millis)
+        .unwrap_or(Duration::from_secs(60))
 }
diff --git a/src/logs.rs b/src/logs.rs
index 934dbb532..b3bb3b02e 100644
--- a/src/logs.rs
+++ b/src/logs.rs
@@ -277,6 +277,7 @@ const PARENT_DISPATCH: &str = "THIRDSHIFT_PARENT_DISPATCH";
 /// shows them, so a skipped pass may print nothing. A child Run prints no
 /// such line, and takes the stamp it was given.
 pub fn begin(begin: Begin) {
+    crate::github::quota::command::begin();
     let mut record = record();
     if matches!(begin, Begin::ChildRun(..)) {
         record.inherit_owner(owner::Owner::inherited());
@@ -284,6 +285,19 @@ pub fn begin(begin: Begin) {
         record.child_dispatch(std::env::var(PARENT_DISPATCH).ok());
     }
     record.begin(begin);
+    drop(record);
+    attach_quota_budget();
+}
+
+fn attach_quota_budget() {
+    if let Ok(owner) = captured_owner()
+        && let Some(path) = owner.log_path()
+        && let Err(error) = crate::github::quota::command::attach(path.into())
+    {
+        crate::progress::step(format!(
+            "warning: could not attach Command quota budget: {error:#}"
+        ));
+    }
 }
 
 /// Give a child Run its exact parent, independently of second-resolution stamps.
@@ -328,6 +342,7 @@ pub(crate) fn pass_fired(repo: &Repo) {
 /// immediate parent, with no Command log of its own.
 pub fn started(work: Work, harness: &Choice) {
     record().started(work, harness);
+    attach_quota_budget();
 }
 
 /// Capture the Custom process's loaded source before recording its start or skip.
@@ -391,6 +406,11 @@ pub fn stage(stage: Stage) {
     record().stage(stage, None);
 }
 
+/// Temporarily overlay the active stage without resetting its timing.
+pub(crate) fn quota_wait(until: Option<&str>) {
+    record().quota_wait(until);
+}
+
 /// Keep the current Session trace, including a Resume's own log, as
 /// `session` enters its stage.
 pub fn session(session: Logged, path: &Path) {
diff --git a/src/logs/command_record.rs b/src/logs/command_record.rs
index 2dc49a226..03b3d23f4 100644
--- a/src/logs/command_record.rs
+++ b/src/logs/command_record.rs
@@ -104,6 +104,8 @@ pub(super) struct CommandRecord {
     #[serde(skip)]
     pub end_time_estimated: bool,
     pub stages: Vec<Stage>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub quota_wait_until: Option<String>,
     pub session_log: Option<PathBuf>,
     pub outcome: Option<String>,
     #[serde(default)]
@@ -441,6 +443,7 @@ impl CommandRecord {
             ended_at: None,
             end_time_estimated: false,
             stages: Vec::new(),
+            quota_wait_until: None,
             session_log: None,
             outcome: None,
             run_metrics: None,
diff --git a/src/logs/reading.rs b/src/logs/reading.rs
index f9a6e9dca..bdabb539f 100644
--- a/src/logs/reading.rs
+++ b/src/logs/reading.rs
@@ -418,13 +418,26 @@ impl Command {
         } else {
             "died"
         };
-        let stage = record.current_stage().map(|stage| CurrentStage {
-            name: stage.name.clone(),
-            began_at: stage.began_at.clone(),
-            age_seconds: DateTime::parse_from_rfc3339(&stage.began_at)
-                .map(|began| now.signed_duration_since(began).num_seconds().max(0))
-                .unwrap_or(0),
-        });
+        let stage = record
+            .current_stage()
+            .map(|stage| CurrentStage {
+                name: record
+                    .quota_wait_until
+                    .as_ref()
+                    .map(|until| format!("Quota wait until {until}"))
+                    .unwrap_or_else(|| stage.name.clone()),
+                began_at: stage.began_at.clone(),
+                age_seconds: DateTime::parse_from_rfc3339(&stage.began_at)
+                    .map(|began| now.signed_duration_since(began).num_seconds().max(0))
+                    .unwrap_or(0),
+            })
+            .or_else(|| {
+                record.quota_wait_until.as_ref().map(|until| CurrentStage {
+                    name: format!("Quota wait until {until}"),
+                    began_at: record.started_at.clone(),
+                    age_seconds: 0,
+                })
+            });
         Self {
             account: None,
             activity: captured_activity::Activity::new(log, record.session_log.as_deref(), now),
diff --git a/src/logs/reading/health.rs b/src/logs/reading/health.rs
index ebbfa869f..e9c62c4ce 100644
--- a/src/logs/reading/health.rs
+++ b/src/logs/reading/health.rs
@@ -80,7 +80,11 @@ pub(super) fn observe(
         if let Some(stage) = &command.stage
             && !StageName::is_dispatch(&stage.name)
         {
-            if let Some(range) = ranges.get(&command.record.repository, &stage.name) {
+            if let Some(range) = command
+                .record
+                .current_stage()
+                .and_then(|underlying| ranges.get(&command.record.repository, &underlying.name))
+            {
                 // The first Slow step starts strictly above the upper range;
                 // the second starts at twice that range, on sampled seconds.
                 for threshold in [
diff --git a/src/logs/reading/tests.rs b/src/logs/reading/tests.rs
index 96cf5224c..7d53b338e 100644
--- a/src/logs/reading/tests.rs
+++ b/src/logs/reading/tests.rs
@@ -66,6 +66,39 @@ fn retained_pull_request_lookup_orders_instants_across_offsets() {
     );
 }
 
+#[test]
+fn quota_wait_keeps_slow_timing_on_the_underlying_stage() {
+    let dir = tempfile::tempdir().unwrap();
+    for number in 1..=8 {
+        let mut past = record(number);
+        past["outcome"] = "ready for review".into();
+        past["ended_at"] = "2026-10-19T11:01:00-04:00".into();
+        past["stages"] = json!([{"name":"CI watch", "began_at":"2026-10-19T11:00:00-04:00", "session_log":null}]);
+        write(dir.path(), &format!("{number}-past.command.json"), &past);
+    }
+    let mut live = record(9);
+    live["stages"] =
+        json!([{"name":"CI watch", "began_at":"2026-10-19T11:30:00-04:00", "session_log":null}]);
+    live["quota_wait_until"] = "2026-10-19T12:01:37-04:00".into();
+    write(dir.path(), "9-live.command.json", &live);
+    fs::write(
+        dir.path().join("acme/widgets/commands/issue/9-live.log"),
+        "still waiting\n",
+    )
+    .unwrap();
+    let snapshot = Snapshot::load(dir.path(), now()).unwrap();
+    let selected = snapshot.resolve("widgets#9").unwrap();
+    let Observation::Record(command) = selected.observation else {
+        panic!("record-backed Command")
+    };
+    assert_eq!(
+        command.stage.as_ref().unwrap().name,
+        "Quota wait until 2026-10-19T12:01:37-04:00"
+    );
+    assert_eq!(command.stage.as_ref().unwrap().age_seconds, 1800);
+    assert!(matches!(command.health, Some(health::Health::Slow { .. })));
+}
+
 #[test]
 fn direct_run_selection_captures_its_owner_and_reloads_retained_work() {
     let dir = tempfile::tempdir().unwrap();
diff --git a/src/logs/recording.rs b/src/logs/recording.rs
index 4a257f07d..b1983a8d0 100644
--- a/src/logs/recording.rs
+++ b/src/logs/recording.rs
@@ -481,6 +481,13 @@ impl<O: Outside> Record<O> {
         self.write_record();
     }
 
+    pub(super) fn quota_wait(&mut self, until: Option<&str>) {
+        if let Some((_, tree)) = &mut self.command_record {
+            tree.active().quota_wait_until = until.map(str::to_owned);
+            self.write_record();
+        }
+    }
+
     pub(super) fn unaddressed_findings(
         &mut self,
         counts: Option<crate::pull_request::UnaddressedFindings>,
diff --git a/src/logs/recording/tests.rs b/src/logs/recording/tests.rs
index d2540c56d..59be114ca 100644
--- a/src/logs/recording/tests.rs
+++ b/src/logs/recording/tests.rs
@@ -292,6 +292,35 @@ fn a_stop_request_in_the_file_adapter_is_logged_before_the_ending() {
     assert!(stopped < activity.find("Run #7 ended: interrupted").unwrap());
 }
 
+#[test]
+fn quota_wait_restores_the_previous_stage_without_restarting_its_clock() {
+    let memory = Scripted::default();
+    let mut record = Record::new(memory.clone());
+    record.begin(Begin::Run(&issue()));
+    record.configured(&config(false));
+    record.started(Work::Run(&issue()), &harness());
+    record.stage(StageName::CiWatch, None);
+    let began = memory
+        .command_record()
+        .current_stage()
+        .unwrap()
+        .began_at
+        .clone();
+    record.quota_wait(Some("2026-11-11T12:01:37Z"));
+    let waiting = memory.command_record();
+    assert_eq!(
+        waiting.quota_wait_until.as_deref(),
+        Some("2026-11-11T12:01:37Z")
+    );
+    assert_eq!(waiting.current_stage().unwrap().began_at, began);
+    record.quota_wait(None);
+    let resumed = memory.command_record();
+    assert!(resumed.quota_wait_until.is_none());
+    assert_eq!(resumed.current_stage().unwrap().name, "CI watch");
+    assert_eq!(resumed.current_stage().unwrap().began_at, began);
+    assert_eq!(resumed.stages.len(), 1);
+}
+
 #[test]
 fn a_command_record_write_failure_warns_once_and_keeps_the_outcome() {
     let memory = Scripted::default();
diff --git a/src/notification.rs b/src/notification.rs
index b7d7296f5..c1d039216 100644
--- a/src/notification.rs
+++ b/src/notification.rs
@@ -235,6 +235,13 @@ impl RunNotification {
             host.as_deref().unwrap_or("unknown host"),
             self.started.elapsed(),
         );
+        match crate::github::quota::command::notification_line() {
+            Ok(Some(line)) => text += &format!("\n{line}\n"),
+            Ok(None) => {}
+            Err(error) => progress::step(format!(
+                "warning: could not read Command quota waits: {error:#}"
+            )),
+        }
         if account.pre_audit_failure.is_some() {
             text += &format!(
                 "Started (UTC): {}\nDiagnostics:  Check this command's stderr on {} at that time (or the scheduler's captured stderr, if scheduled).\n",
diff --git a/tests/console.rs b/tests/console.rs
index 315470c6c..ff83961aa 100644
--- a/tests/console.rs
+++ b/tests/console.rs
@@ -297,6 +297,30 @@ fn console_pages_show_the_running_thirdshift_version() {
     }
 }
 
+#[test]
+fn quota_wait_stage_is_shared_by_status_show_and_console_and_resumes() {
+    let home = tempfile::tempdir().unwrap();
+    configure(home.path());
+    let mut value = record(home.path(), 7, None, 0);
+    value["quota_wait_until"] = "2026-11-11T12:01:37Z".into();
+    write_record(home.path(), 7, &value);
+    let binary = Path::new(env!("CARGO_BIN_EXE_thirdshift"));
+    let console = Console::start(binary, home.path());
+    let name = "Quota wait until";
+    let mut url = reqwest::Url::parse("http://localhost/peek").unwrap();
+    url.query_pairs_mut().append_pair("command", "widgets#7");
+    let peek_path = format!("/peek?{}", url.query().unwrap());
+    for path in ["/", &peek_path] {
+        let text = console.get(path).text().unwrap();
+        assert!(text.contains(name), "{path}: {text}");
+    }
+    value["quota_wait_until"] = Value::Null;
+    write_record(home.path(), 7, &value);
+    let text = console.get(&peek_path).text().unwrap();
+    assert!(!text.contains(name), "{text}");
+    assert!(text.contains("implement"), "{text}");
+}
+
 #[test]
 fn command_changes_push_events_over_http() {
     let home = tempfile::tempdir().unwrap();
diff --git a/tests/quota_wait.rs b/tests/quota_wait.rs
new file mode 100644
index 000000000..ad31f51b5
--- /dev/null
+++ b/tests/quota_wait.rs
@@ -0,0 +1,292 @@
+mod support;
+
+use serde_json::json;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+use support::Scenario;
+
+const COMMIT: &str =
+    "echo feature > feature.txt\ngit add feature.txt\ngit commit -qm 'Add feature'\n";
+const PR: &str =
+    "gh pr create --base main --head issue-7 --title 'Add feature' --body 'Closes #7' --draft\n";
+
+#[test]
+fn delivery_write_waits_for_primary_quota_and_notifies_once() {
+    let scenario = Scenario::new();
+    scenario.agent_does(&format!("{COMMIT}{PR}"));
+    let reset = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+        + 3;
+    let mut state = scenario.gh_state();
+    state["fail_next"] = json!({"call":"pr ready", "times":1,
+        "error":"GraphQL: API rate limit exceeded (HTTP 403)"});
+    state["rate_limits"] = json!({"graphql":{"remaining":0,"reset":reset}});
+    scenario.write_gh_state(&state);
+
+    let result = scenario.run_with_env(
+        &[&scenario.issue_url(7)],
+        &[("THIRDSHIFT_QUOTA_MINUTE_MS", "1")],
+    );
+
+    assert_eq!(result.code, Some(0), "{}", result.stderr);
+    assert!(
+        result.stderr.contains("Quota wait until"),
+        "{}",
+        result.stderr
+    );
+    assert_eq!(scenario.gh_calls_of("pr", "ready").len(), 2);
+    let (_, notification) = support::resend::saved_notification(&scenario, "issue");
+    assert_eq!(
+        notification
+            .matches("for the GitHub quota (graphql)")
+            .count(),
+        1,
+        "{notification}"
+    );
+    assert!(
+        !scenario.gh_state()["labels"]["7"]
+            .as_array()
+            .unwrap()
+            .contains(&json!("agent-failed"))
+    );
+}
+
+#[test]
+fn ci_watch_waits_until_reset_then_delivers_without_a_repair() {
+    let scenario = Scenario::new();
+    scenario.agent_does(&format!(r#"{COMMIT}{PR}
+gh fake checks "$(git rev-parse HEAD)" '[{{"name":"test","conclusion":"success","url":"https://ci.example/test"}}]'
+python3 - <<'PY'
+import json, os, time
+path = os.environ['FAKE_GH_STATE']
+with open(path) as f: state = json.load(f)
+state['fail_next'] = {{'call':'api --paginate --jq .check_runs[]','times':1,'error':'API rate limit exceeded (HTTP 403)'}}
+state['rate_limits'] = {{'core':{{'remaining':0,'reset':int(time.time())+3}}}}
+with open(path, 'w') as f: json.dump(state, f)
+PY
+"#));
+    let result = scenario.run_with_env(
+        &[&scenario.issue_url(7)],
+        &[("THIRDSHIFT_QUOTA_MINUTE_MS", "1")],
+    );
+    assert_eq!(result.code, Some(0), "{}", result.stderr);
+    assert!(result.stderr.contains("CI passed"), "{}", result.stderr);
+    assert!(
+        result.stderr.contains("Quota wait until"),
+        "{}",
+        result.stderr
+    );
+    let now = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_secs();
+    assert!(
+        now >= scenario.gh_state()["rate_limits"]["core"]["reset"]
+            .as_u64()
+            .unwrap()
+    );
+    assert_eq!(
+        scenario.claude_calls().len(),
+        1,
+        "quota wait started a Repair"
+    );
+    assert_eq!(scenario.gh_state()["prs"][0]["isDraft"], false);
+    let (_, text) = support::resend::saved_notification(&scenario, "issue");
+    assert_eq!(
+        text.matches("for the GitHub quota (core)").count(),
+        1,
+        "{text}"
+    );
+    assert!(
+        !scenario
+            .issue_labels(7)
+            .iter()
+            .any(|label| label == "agent-failed")
+    );
+}
+
+#[test]
+fn secondary_limit_stops_after_five_retries_without_a_quota_wait() {
+    for failures in [1, 6] {
+        let scenario = Scenario::new();
+        scenario.agent_does(&format!("{COMMIT}{PR}"));
+        let mut state = scenario.gh_state();
+        state["fail_next"] = json!({"call":"pr ready", "times":failures,
+            "error":"GraphQL: secondary rate limit exceeded (HTTP 429)"});
+        scenario.write_gh_state(&state);
+        let result = scenario.run_with_env(
+            &[&scenario.issue_url(7)],
+            &[("THIRDSHIFT_QUOTA_MINUTE_MS", "10")],
+        );
+        assert_eq!(
+            result.code,
+            Some(if failures == 1 { 0 } else { 1 }),
+            "{}",
+            result.stderr
+        );
+        assert_eq!(
+            scenario.gh_calls_of("pr", "ready").len(),
+            failures.min(5) + 1
+        );
+        assert!(
+            !result.stderr.contains("Quota wait until"),
+            "{}",
+            result.stderr
+        );
+        let (_, text) = support::resend::saved_notification(&scenario, "issue");
+        assert!(!text.contains("for the GitHub quota"), "{text}");
+        assert!(!scenario.path("home/.thirdshift/github-quota.json").exists());
+    }
+}
+
+#[test]
+fn a_primary_wait_beyond_the_cap_returns_the_original_github_failure() {
+    let scenario = Scenario::new();
+    scenario.agent_does(&format!("{COMMIT}{PR}"));
+    let mut state = scenario.gh_state();
+    state["fail_next"] = json!({"call":"pr ready", "times":1,
+        "error":"GraphQL: API rate limit exceeded (HTTP 403)"});
+    state["rate_limits"] = json!({"graphql":{"remaining":0,"reset":4102444800u64}});
+    scenario.write_gh_state(&state);
+    let result = scenario.run(&[&scenario.issue_url(7)]);
+    assert_eq!(result.code, Some(1), "{}", result.stderr);
+    assert!(
+        result.stderr.contains(
+            "gh pr ready 1 --repo acme/widgets failed: GraphQL: API rate limit exceeded (HTTP 403)"
+        ),
+        "{}",
+        result.stderr
+    );
+    assert_eq!(scenario.gh_calls_of("pr", "ready").len(), 1);
+    let (_, text) = support::resend::saved_notification(&scenario, "issue");
+    assert!(!text.contains("for the GitHub quota"), "{text}");
+}
+
+fn wait_for_quota_stage(scenario: &Scenario) {
+    let deadline = Instant::now() + Duration::from_secs(30);
+    loop {
+        if scenario.command_record("home/.thirdshift/logs/acme/widgets/commands/issue")
+            ["quota_wait_until"].is_string() { return; }
+        assert!(
+            Instant::now() < deadline,
+            "Command never entered Quota wait"
+        );
+        std::thread::sleep(Duration::from_millis(20));
+    }
+}
+
+#[test]
+fn stop_cancels_an_ordinary_wait_but_claim_ending_waits_and_restores_its_stage() {
+    let scenario = Scenario::new();
+    scenario.issue_labelled(7, &["ready-for-agent"]);
+    scenario.agent_does(&format!(
+        "{COMMIT}{PR}touch '{}'\n",
+        scenario.path("started").display()
+    ));
+    let mut state = scenario.gh_state();
+    state["fail_next"] = json!({"call":"pr ready", "times":1,
+        "error":"GraphQL: API rate limit exceeded (HTTP 403)"});
+    let reset = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+        + 3600;
+    state["rate_limits"] = json!({"graphql":{"remaining":0,"reset":reset}});
+    scenario.write_gh_state(&state);
+    let held = scenario.run_until(
+        &[&scenario.issue_url(7)],
+        &[("THIRDSHIFT_QUOTA_MINUTE_MS", "1")],
+        "started",
+    );
+    wait_for_quota_stage(&scenario);
+    for args in [vec!["status"], vec!["show", "widgets#7"]] {
+        let shown = scenario.run(&args);
+        assert_eq!(shown.code, Some(0), "{}", shown.stderr);
+        assert!(
+            shown.stdout.contains("Quota wait until"),
+            "{}",
+            shown.stdout
+        );
+    }
+    let mut state = scenario.gh_state();
+    state["fail_next"] = json!({"call":"api --method PUT", "times":1,
+        "error":"API rate limit exceeded (HTTP 403)"});
+    let reset = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+        + 3;
+    state["rate_limits"]["core"] = json!({"remaining":0,"reset":reset});
+    scenario.write_gh_state(&state);
+    let stopped_at = Instant::now();
+    let stopped = scenario.run(&["stop", "widgets#7"]);
+    let result = held.finish();
+    assert_eq!(stopped.code, Some(0), "{}", stopped.stderr);
+    assert_eq!(result.code, Some(1), "{}", result.stderr);
+    assert!(
+        stopped_at.elapsed() < Duration::from_secs(30),
+        "ordinary hour wait survived Stop"
+    );
+    assert!(
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap()
+            .as_secs()
+            >= reset
+    );
+    assert_eq!(scenario.gh_state()["fail_next"]["times"], 0);
+    assert!(
+        scenario
+            .issue_labels(7)
+            .contains(&"needs-triage".to_string())
+    );
+    assert!(
+        !scenario
+            .issue_labels(7)
+            .contains(&"agent-failed".to_string())
+    );
+    let record = scenario.command_record("home/.thirdshift/logs/acme/widgets/commands/issue");
+    assert!(record["quota_wait_until"].is_null(), "{record}");
+    let (_, text) = support::resend::saved_notification(&scenario, "issue");
+    assert_eq!(
+        text.matches("for the GitHub quota (core, graphql)").count(),
+        1,
+        "{text}"
+    );
+}
+
+#[test]
+fn a_child_tickets_quota_wait_belongs_to_its_spec_commands_notification() {
+    let scenario = Scenario::new();
+    scenario.spec_has_tickets(20, &[(21, &[])]);
+    scenario.agent_does_for(21, &format!("{COMMIT}gh pr create --base issue-20 --head issue-21 --title Ticket --body 'Closes #21' --draft\n"));
+    let mut state = scenario.gh_state();
+    let reset = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+        + 3;
+    state["fail_next"] = json!({"call":"pr ready", "times":1,
+        "error":"GraphQL: API rate limit exceeded (HTTP 403)"});
+    state["rate_limits"] = json!({"graphql":{"remaining":0,"reset":reset}});
+    scenario.write_gh_state(&state);
+    let result = scenario.run_with_env(
+        &[&scenario.issue_url(20)],
+        &[("THIRDSHIFT_QUOTA_MINUTE_MS", "1")],
+    );
+    assert_eq!(result.code, Some(0), "{}", result.stderr);
+    let (_, text) = support::resend::saved_notification(&scenario, "issue");
+    assert_eq!(
+        text.matches("for the GitHub quota (graphql)").count(),
+        1,
+        "{text}"
+    );
+    let sidecars = scenario
+        .entries("home/.thirdshift/logs/acme/widgets/commands/issue")
+        .into_iter()
+        .filter(|name| name.ends_with(".quota-wait.json"))
+        .collect::<Vec<_>>();
+    assert_eq!(sidecars.len(), 1, "{sidecars:?}");
+    assert!(sidecars[0].starts_with("20-"), "{sidecars:?}");
+}

From c87c82dc1e5cb2e0a994961e17f2b353c2f820ea Mon Sep 17 00:00:00 2001
From: Jacob Stephens <jstephens@etadventures.com>
Date: Tue, 10 Nov 2026 22:48:05 -0500
Subject: [PATCH 2/8] Compare quota stage restoration with the initial stage
 history

---
 src/logs/recording/tests.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/logs/recording/tests.rs b/src/logs/recording/tests.rs
index 59be114ca..959f626b5 100644
--- a/src/logs/recording/tests.rs
+++ b/src/logs/recording/tests.rs
@@ -300,6 +300,7 @@ fn quota_wait_restores_the_previous_stage_without_restarting_its_clock() {
     record.configured(&config(false));
     record.started(Work::Run(&issue()), &harness());
     record.stage(StageName::CiWatch, None);
+    let stages_before = memory.command_record().stages.len();
     let began = memory
         .command_record()
         .current_stage()
@@ -318,7 +319,7 @@ fn quota_wait_restores_the_previous_stage_without_restarting_its_clock() {
     assert!(resumed.quota_wait_until.is_none());
     assert_eq!(resumed.current_stage().unwrap().name, "CI watch");
     assert_eq!(resumed.current_stage().unwrap().began_at, began);
-    assert_eq!(resumed.stages.len(), 1);
+    assert_eq!(resumed.stages.len(), stages_before);
 }
 
 #[test]

From 5768737effe71416aab669e7c03259409304db06 Mon Sep 17 00:00:00 2001
From: Jacob Stephens <jstephens@etadventures.com>
Date: Tue, 10 Nov 2026 22:48:56 -0500
Subject: [PATCH 3/8] Share GitHub quota classification across recovery
 policies

---
 src/github/check_read.rs | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/src/github/check_read.rs b/src/github/check_read.rs
index ae32c9b1f..cf0e4086a 100644
--- a/src/github/check_read.rs
+++ b/src/github/check_read.rs
@@ -45,12 +45,7 @@ pub(crate) fn is_transient(error: &anyhow::Error) -> bool {
     let stderr = failure.stderr.trim().to_ascii_lowercase();
     // Quota exhaustion belongs to quota-aware deferral, not a short retry.
     // gh can report GraphQL quota errors with or without an HTTP status.
-    if stderr.contains("api rate limit")
-        || stderr.contains("secondary rate limit")
-        || stderr.contains("abuse detection")
-        || stderr.contains("rate_limited")
-        || stderr.contains("rate_limit_exceeded")
-    {
+    if super::quota::Limit::of(&[], stderr.as_bytes()).is_some() {
         return false;
     }
     // gh reports HTTP status in stderr. Prefer it to incidental prose, so

From e61423a9944fcd7e909ae6b3fa8c57ea9140350f Mon Sep 17 00:00:00 2001
From: Jacob Stephens <jstephens@etadventures.com>
Date: Tue, 10 Nov 2026 22:55:11 -0500
Subject: [PATCH 4/8] Keep preflight quota waits visible and selectable for
 Stop

---
 GLOSSARY.md                 |  2 +-
 src/command.rs              |  3 ++
 src/github/quota/command.rs |  2 +-
 src/github/quota/wait.rs    |  3 ++
 src/logs.rs                 | 33 +++++++++++++++++++++
 src/logs/command_record.rs  |  8 ++++-
 src/logs/owner.rs           |  6 ++++
 src/logs/recording.rs       | 58 +++++++++++++++++++++++++++++++++++--
 tests/quota_wait.rs         | 50 ++++++++++++++++++++++++++++++++
 9 files changed, 160 insertions(+), 5 deletions(-)

diff --git a/GLOSSARY.md b/GLOSSARY.md
index f7788f99a..3ce915a89 100644
--- a/GLOSSARY.md
+++ b/GLOSSARY.md
@@ -298,7 +298,7 @@ The token counts and cost reported in one **Session trace**, grouped by observed
 A **Command**'s whole tree of work, its child **Ticket runs** and all of their **Session traces** included. Their shared identity keeps the tree together across sessions.
 
 **Command log**:
-Everything one **Ticket run**, **Spec run**, **Architect run**, **Pickup run**, **Security run** or **Custom process** printed, kept in a file of its own with its repository's other logs, stamped like its **Session traces**. The start stamp is for display and grouping; Commands with the same start time still have distinct storage ownership for their Command logs, Session traces and **Command records**. An Architect run's, Pickup run's, Security run's or Custom process's covers the Spec runs or Ticket runs it dispatched, and a Spec run's covers its **Ticket runs**, as a Ticket run's covers its **Base fix**: none of those keeps one of its own. It is kept once the command starts work: a Pickup run, Architect run or Security run skipped before doing any work keeps none, and neither does a Ticket run that fails before it starts work, such as on **Origin match**.
+Everything one **Ticket run**, **Spec run**, **Architect run**, **Pickup run**, **Security run** or **Custom process** printed, kept in a file of its own with its repository's other logs, stamped like its **Session traces**. The start stamp is for display and grouping; Commands with the same start time still have distinct storage ownership for their Command logs, Session traces and **Command records**. An Architect run's, Pickup run's, Security run's or Custom process's covers the Spec runs or Ticket runs it dispatched, and a Spec run's covers its **Ticket runs**, as a Ticket run's covers its **Base fix**: none of those keeps one of its own. It is kept once the command starts work, or earlier when a **Quota wait** needs a visible, stoppable Command record. Without such a wait, a Pickup run, Architect run or Security run skipped before doing any work keeps none, and neither does a Ticket run that fails before it starts work, such as on **Origin match**.
 _Avoid_: cron log, output log, run log (a **Ticket run** is one kind of command)
 
 **Log inventory**:
diff --git a/src/command.rs b/src/command.rs
index f8d34368f..97ecc59f7 100644
--- a/src/command.rs
+++ b/src/command.rs
@@ -117,6 +117,9 @@ pub fn start(
     // First, so no interrupt can end the command once its notification is
     // checked.
     interrupt::install().map_err(|error| failure(&error))?;
+    if let About::Issue(issue) = &about {
+        logs::preflight_issue(issue);
+    }
     let notification = if started.is_some() {
         Some(
             RunNotification::new(ask(&config), &config.email, about)
diff --git a/src/github/quota/command.rs b/src/github/quota/command.rs
index 74515c94a..15096a2bb 100644
--- a/src/github/quota/command.rs
+++ b/src/github/quota/command.rs
@@ -49,7 +49,7 @@ pub(crate) fn attach(path: PathBuf) -> Result<()> {
         command.path = Some(path.with_extension("quota-wait.json"));
         // Before log allocation, only the parent can have waited. Commands
         // that never wait need no quota sidecar.
-        if !totals.waited.is_zero() {
+        if !totals.budget.is_empty() {
             command.update(|stored| *stored = totals)?;
         }
     }
diff --git a/src/github/quota/wait.rs b/src/github/quota/wait.rs
index fa1dfbe2c..343bc4cd7 100644
--- a/src/github/quota/wait.rs
+++ b/src/github/quota/wait.rs
@@ -14,6 +14,9 @@ pub(crate) struct WaitBudget {
 pub(crate) struct WaitCapExceeded;
 
 impl WaitBudget {
+    pub(super) fn is_empty(&self) -> bool {
+        self.total.is_zero()
+    }
     pub fn next(&mut self, reset: DateTime<Utc>) -> Result<Duration, WaitCapExceeded> {
         self.next_with(reset, Utc::now, || rand::random_range(0..=60))
     }
diff --git a/src/logs.rs b/src/logs.rs
index b3bb3b02e..d170d9a86 100644
--- a/src/logs.rs
+++ b/src/logs.rs
@@ -184,6 +184,12 @@ pub enum Begin<'a> {
 /// The work a command starts.
 #[derive(Clone, Copy)]
 pub enum Work<'a> {
+    /// A Command still in preflight, retained only because it hit a Quota wait.
+    Starting {
+        repo: &'a Repo,
+        command: CommandKind,
+        issue: Option<&'a IssueUrl>,
+    },
     /// A Run on its issue.
     Run(&'a IssueUrl),
     /// A Base fix, a child Run into the Run's Base branch.
@@ -328,6 +334,10 @@ pub fn configured(config: &UserConfig) {
     record().configured(config);
 }
 
+pub(crate) fn preflight_issue(issue: &IssueUrl) {
+    record().preflight_issue(issue.clone());
+}
+
 /// Keep the Pass's latest start once its repository is known, before gates.
 pub(crate) fn pass_fired(repo: &Repo) {
     record().pass_fired(repo);
@@ -408,7 +418,14 @@ pub fn stage(stage: Stage) {
 
 /// Temporarily overlay the active stage without resetting its timing.
 pub(crate) fn quota_wait(until: Option<&str>) {
+    if until.is_some() && record().needs_quota_repo() {
+        let repo = crate::launch::repo().ok();
+        record().preflight_repo(repo);
+    }
     record().quota_wait(until);
+    if until.is_some() {
+        attach_quota_budget();
+    }
 }
 
 /// Keep the current Session trace, including a Resume's own log, as
@@ -594,6 +611,7 @@ impl<'a> Work<'a> {
     fn process(self) -> crate::processes::Identity {
         use crate::processes::Identity;
         let file = match self {
+            Self::Starting { .. } => return Identity::default(),
             Self::Run(_) | Self::BaseFix(_) => "ticket-run",
             Self::SpecRun(_) => "spec-run",
             Self::ArchitectRun(_) => "architect-run",
@@ -611,6 +629,7 @@ impl<'a> Work<'a> {
 
     fn initial_stage(self) -> Option<Stage> {
         match self {
+            Work::Starting { .. } => None,
             Work::Run(_) | Work::BaseFix(_) => Some(Stage::Implement),
             Work::SpecRun(_) => Some(Stage::Tickets),
             Work::ArchitectRun(_) => Some(Stage::ArchitectureReview),
@@ -626,6 +645,7 @@ impl<'a> Work<'a> {
     /// The repository whose work it records.
     fn repo(self) -> Repo {
         match self {
+            Work::Starting { repo, .. } => repo.clone(),
             Work::Run(issue) | Work::BaseFix(issue) | Work::SpecRun(issue) => issue.repo(),
             Work::PickupRun(listed) => listed.issue.repo(),
             Work::ArchitectRun(repo)
@@ -642,6 +662,18 @@ impl<'a> Work<'a> {
     /// Its kind, in the Activity log.
     fn kind(self) -> Kind {
         match self {
+            Work::Starting { command, .. } => match command {
+                CommandKind::Issue => Kind::Run,
+                CommandKind::Architect => Kind::Pass(Pass::Architect),
+                CommandKind::Pickup => Kind::Pass(Pass::Pickup),
+                CommandKind::Secure => Kind::Pass(Pass::Security),
+                CommandKind::Scoring => Kind::ScoringRun,
+                CommandKind::Review => Kind::ReviewRun,
+                CommandKind::Fix => Kind::FixRun,
+                CommandKind::Triage => Kind::TriageRun,
+                CommandKind::Experiment => Kind::Experiment,
+                CommandKind::Process => Kind::Process,
+            },
             Work::Run(_) | Work::BaseFix(_) => Kind::Run,
             Work::SpecRun(_) => Kind::SpecRun,
             Work::PickupRun(_) => Kind::Pass(Pass::Pickup),
@@ -659,6 +691,7 @@ impl<'a> Work<'a> {
     /// Its issue, if it has one.
     pub(crate) fn issue_url(self) -> Option<&'a IssueUrl> {
         match self {
+            Work::Starting { issue, .. } => issue,
             Work::Run(issue) | Work::BaseFix(issue) | Work::SpecRun(issue) => Some(issue),
             Work::PickupRun(listed) => Some(&listed.issue),
             Work::ArchitectRun(_)
diff --git a/src/logs/command_record.rs b/src/logs/command_record.rs
index 03b3d23f4..f097166a6 100644
--- a/src/logs/command_record.rs
+++ b/src/logs/command_record.rs
@@ -258,6 +258,7 @@ impl StageName {
     /// The stage a pass enters while `work`, the Command it dispatched, runs.
     pub(super) fn dispatched(work: Work<'_>) -> Self {
         match work {
+            Work::Starting { .. } => Self::ProcessStep,
             Work::SpecRun(_) => Self::DispatchedSpecRun,
             Work::Run(_)
             | Work::BaseFix(_)
@@ -395,7 +396,8 @@ impl CommandRecord {
             // The Ready issue listing named a Pickup run's issue before it started.
             title: match work {
                 Work::PickupRun(listed) => Some(listed.title.clone()),
-                Work::Run(_)
+                Work::Starting { .. }
+                | Work::Run(_)
                 | Work::BaseFix(_)
                 | Work::SpecRun(_)
                 | Work::ArchitectRun(_)
@@ -409,6 +411,10 @@ impl CommandRecord {
             },
         });
         let name = match work {
+            Work::Starting { command, issue, .. } => match issue {
+                Some(issue) => format!("{}#{}", issue.repo_slug(), issue.number),
+                None => format!("{}-{stamp}", command.folder()),
+            },
             Work::ArchitectRun(_) => format!("architect-{stamp}"),
             Work::SecurityRun(_) => format!("secure-{stamp}"),
             Work::ScoringRun(_) => format!("scoring-{stamp}"),
diff --git a/src/logs/owner.rs b/src/logs/owner.rs
index ee17ede39..4786e8689 100644
--- a/src/logs/owner.rs
+++ b/src/logs/owner.rs
@@ -136,6 +136,12 @@ pub(super) fn allocate<F: Files>(
     stamp: &str,
 ) -> Result<Allocation<F::CommandLog>> {
     let (kind, subject) = match work {
+        Work::Starting { command, issue, .. } => (
+            command,
+            issue
+                .map(|issue| format!("{}-", issue.number))
+                .unwrap_or_default(),
+        ),
         Work::Run(issue) | Work::BaseFix(issue) | Work::SpecRun(issue) => {
             (CommandKind::Issue, format!("{}-", issue.number))
         }
diff --git a/src/logs/recording.rs b/src/logs/recording.rs
index b1983a8d0..1642a716f 100644
--- a/src/logs/recording.rs
+++ b/src/logs/recording.rs
@@ -37,6 +37,9 @@ pub(super) struct Record<O: Outside> {
     /// repository has them.
     config_warnings: Vec<String>,
     command_record: Option<(PathBuf, CommandTree)>,
+    preflight_repo: Option<Repo>,
+    preflight_issue: Option<crate::issue::IssueUrl>,
+    quota_record: bool,
     custom_process: Option<crate::processes::Identity>,
     parent_record: Option<PathBuf>,
     parent_dispatch: Option<String>,
@@ -98,6 +101,9 @@ impl<O: Outside> Record<O> {
             activity_warned: false,
             config_warnings: Vec::new(),
             command_record: None,
+            preflight_repo: None,
+            preflight_issue: None,
+            quota_record: false,
             custom_process: None,
             parent_record: None,
             parent_dispatch: None,
@@ -107,6 +113,9 @@ impl<O: Outside> Record<O> {
     }
 
     pub(super) fn begin(&mut self, begin: Begin) {
+        if let Begin::Run(issue) = &begin {
+            self.preflight_issue((*issue).clone());
+        }
         self.command = match &begin {
             Begin::Run(_) => CommandKind::Issue,
             Begin::ChildRun(_, command) => *command,
@@ -162,6 +171,21 @@ impl<O: Outside> Record<O> {
         }
     }
 
+    pub(super) fn preflight_repo(&mut self, repo: Option<Repo>) {
+        if self.preflight_repo.is_none() {
+            self.preflight_repo = repo;
+        }
+    }
+
+    pub(super) fn needs_quota_repo(&self) -> bool {
+        self.command_record.is_none() && self.preflight_repo.is_none()
+    }
+
+    pub(super) fn preflight_issue(&mut self, issue: crate::issue::IssueUrl) {
+        self.preflight_repo = Some(issue.repo());
+        self.preflight_issue = Some(issue);
+    }
+
     /// Hand on the progress line `message`, to the terminal even while a
     /// quiet pass holds its other lines, and to the Command log as any
     /// other.
@@ -255,7 +279,7 @@ impl<O: Outside> Record<O> {
         let stamp = self.stamp();
         let began = matches!(self.command_log, Log::Held { .. });
         self.keep(&root, work, &stamp);
-        if began {
+        if began || self.quota_record {
             self.start_record(work, harness);
         }
         self.step(format_args!("sessions run on {harness}"));
@@ -273,7 +297,8 @@ impl<O: Outside> Record<O> {
             issue: work.issue(),
             process: match work {
                 Work::Process { name, .. } => Some((*name).to_string()),
-                Work::Run(_)
+                Work::Starting { .. }
+                | Work::Run(_)
                 | Work::BaseFix(_)
                 | Work::SpecRun(_)
                 | Work::PickupRun(_)
@@ -335,6 +360,12 @@ impl<O: Outside> Record<O> {
     fn start_record(&mut self, work: Work, harness: &Choice) {
         let stamp = self.stamp();
         let mut facts = CommandRecord::new(work, &stamp, harness, self.outside.now());
+        if self.quota_record
+            && let Some((_, tree)) = &self.command_record
+        {
+            facts.started_at = tree.command.started_at.clone();
+        }
+        self.quota_record = false;
         if matches!(work, Work::Process { .. })
             && let Some(identity) = &self.custom_process
         {
@@ -482,6 +513,29 @@ impl<O: Outside> Record<O> {
     }
 
     pub(super) fn quota_wait(&mut self, until: Option<&str>) {
+        if until.is_some()
+            && self.command_record.is_none()
+            && let Some(repo) = self.preflight_repo.clone()
+            && self.logs_dir.is_some()
+            && (!self.child || self.preflight_issue.is_some())
+        {
+            let issue = self.preflight_issue.clone();
+            let work = Work::Starting {
+                repo: &repo,
+                command: self.command,
+                issue: issue.as_ref(),
+            };
+            if !self.child {
+                let stamp = self.stamp();
+                self.keep(&self.root(&repo), work, &stamp);
+            }
+            self.start_record(work, &Choice::default());
+            if let Some((_, tree)) = &mut self.command_record {
+                // No Harness has been selected or launched during preflight.
+                tree.command.harness = "not started".into();
+            }
+            self.quota_record = true;
+        }
         if let Some((_, tree)) = &mut self.command_record {
             tree.active().quota_wait_until = until.map(str::to_owned);
             self.write_record();
diff --git a/tests/quota_wait.rs b/tests/quota_wait.rs
index ad31f51b5..a729fcde5 100644
--- a/tests/quota_wait.rs
+++ b/tests/quota_wait.rs
@@ -290,3 +290,53 @@ fn a_child_tickets_quota_wait_belongs_to_its_spec_commands_notification() {
     assert_eq!(sidecars.len(), 1, "{sidecars:?}");
     assert!(sidecars[0].starts_with("20-"), "{sidecars:?}");
 }
+
+#[test]
+fn preflight_quota_wait_is_visible_and_can_be_stopped() {
+    use std::{fs, process::Stdio};
+    let scenario = Scenario::new();
+    let reset = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+        + 3600;
+    let mut state = scenario.gh_state();
+    state["fail_next"] = json!({"call":"api graphql", "times":1,
+        "error":"GraphQL: API rate limit exceeded (HTTP 403)"});
+    state["rate_limits"] = json!({"graphql":{"remaining":0,"reset":reset}});
+    scenario.write_gh_state(&state);
+    let stderr_path = scenario.path("preflight.stderr");
+    let owned = support::child_lifetime::OwnedRuns::new();
+    let mut command = scenario.command(&[&scenario.issue_url(7)]);
+    command
+        .env("THIRDSHIFT_QUOTA_MINUTE_MS", "1")
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(fs::File::create(&stderr_path).unwrap());
+    let mut child = owned.spawn(&mut command);
+    let deadline = Instant::now() + Duration::from_secs(30);
+    loop {
+        let stderr = fs::read_to_string(&stderr_path).unwrap();
+        if stderr.contains("Quota wait until") {
+            break;
+        }
+        assert!(
+            child.try_wait().is_none() && Instant::now() < deadline,
+            "{stderr}"
+        );
+        std::thread::sleep(Duration::from_millis(20));
+    }
+    for args in [vec!["status"], vec!["show", "widgets#7"]] {
+        let result = scenario.run(&args);
+        assert_eq!(result.code, Some(0), "{}", result.stderr);
+        assert!(
+            result.stdout.contains("Quota wait until"),
+            "{}",
+            result.stdout
+        );
+    }
+    let stopped = scenario.run(&["stop", "widgets#7"]);
+    assert_eq!(stopped.code, Some(0), "{}", stopped.stderr);
+    assert!(!child.wait().success());
+    assert!(scenario.claude_calls().is_empty());
+}

From c74d4568da416c817ffe77f4633afcab2558cacd Mon Sep 17 00:00:00 2001
From: Jacob Stephens <jstephens@etadventures.com>
Date: Tue, 10 Nov 2026 22:58:06 -0500
Subject: [PATCH 5/8] Finish quota-created Pass records when the Pass skips

---
 src/logs/recording.rs |  3 +++
 tests/quota_wait.rs   | 27 +++++++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/src/logs/recording.rs b/src/logs/recording.rs
index 1642a716f..ce49b5a58 100644
--- a/src/logs/recording.rs
+++ b/src/logs/recording.rs
@@ -415,6 +415,9 @@ impl<O: Outside> Record<O> {
     }
 
     pub(super) fn skipped(&mut self, pass: Pass, repo: &Repo, reason: impl Display) {
+        if self.quota_record {
+            self.outcome("skipped", Some(&reason.to_string()));
+        }
         let kind = Kind::Pass(pass);
         self.activity_write(
             &self.root(repo),
diff --git a/tests/quota_wait.rs b/tests/quota_wait.rs
index a729fcde5..6cc1f2782 100644
--- a/tests/quota_wait.rs
+++ b/tests/quota_wait.rs
@@ -340,3 +340,30 @@ fn preflight_quota_wait_is_visible_and_can_be_stopped() {
     assert!(!child.wait().success());
     assert!(scenario.claude_calls().is_empty());
 }
+
+#[test]
+fn a_pass_that_waited_before_skipping_finishes_its_command_record() {
+    let scenario = Scenario::new();
+    let reset = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+        + 2;
+    let mut state = scenario.gh_state();
+    state["fail_next"] = json!({"call":"api --paginate --jq", "times":1,
+        "error":"API rate limit exceeded (HTTP 403)"});
+    state["rate_limits"] = json!({"core":{"remaining":0,"reset":reset}});
+    scenario.write_gh_state(&state);
+    let result = scenario.run_with_env(&["pickup"], &[("THIRDSHIFT_QUOTA_MINUTE_MS", "1")]);
+    assert_eq!(result.code, Some(0), "{}", result.stderr);
+    assert!(
+        result.stderr.contains("Quota wait until"),
+        "{}",
+        result.stderr
+    );
+    let record = scenario.command_record("home/.thirdshift/logs/acme/widgets/commands/pickup");
+    assert_eq!(record["outcome"], "skipped", "{record}");
+    assert!(record["ended_at"].is_string(), "{record}");
+    let shown = scenario.run(&["status"]);
+    assert!(!shown.stdout.contains("Died"), "{}", shown.stdout);
+}

From 44255632a99156b30e201de6ae3e927cdfb72c2e Mon Sep 17 00:00:00 2001
From: Jacob Stephens <jstephens@etadventures.com>
Date: Tue, 10 Nov 2026 23:01:38 -0500
Subject: [PATCH 6/8] Handle preflight work in the Run test adapter

---
 src/run.rs | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/run.rs b/src/run.rs
index e5251bd72..9cd5b2051 100644
--- a/src/run.rs
+++ b/src/run.rs
@@ -777,7 +777,8 @@ mod tests {
             let spec_run = match work {
                 Work::Run(_) | Work::BaseFix(_) => false,
                 Work::SpecRun(_) => true,
-                Work::PickupRun(_)
+                Work::Starting { .. }
+                | Work::PickupRun(_)
                 | Work::ArchitectRun(_)
                 | Work::SecurityRun(_)
                 | Work::ScoringRun(_)

From b0caa96200d0821bb21efcc8d647d11f68c6e2bf Mon Sep 17 00:00:00 2001
From: Jacob Stephens <jstephens@etadventures.com>
Date: Tue, 10 Nov 2026 23:39:31 -0500
Subject: [PATCH 7/8] Keep Security notification privacy checks at the quota
 wait cap

---
 tests/security_run.rs | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/tests/security_run.rs b/tests/security_run.rs
index fc814c854..ea8faade1 100644
--- a/tests/security_run.rs
+++ b/tests/security_run.rs
@@ -4073,11 +4073,19 @@ fn pre_audit_github_failures_report_a_safe_cause_without_claiming_an_audit_ran()
             github["failing_stderr"] = json!(format!(
                 "{diagnostic} token=PRIVATE-CREDENTIAL Private candidate write-up. Private provider/verifier diagnostic."
             ));
+            // A reset beyond the Command's cap reaches the original failure
+            // path whose notification privacy this test checks.
+            github["rate_limits"] = json!({
+                "core": {"remaining": 0, "reset": 4102444800u64},
+                "graphql": {"remaining": 0, "reset": 4102444800u64}
+            });
             scenario.write_gh_state(&github);
             let resend = ResendStandIn::replying(200, r#"{"id":"1"}"#);
+            let mut env = resend_env(&resend).to_vec();
+            env.push(("THIRDSHIFT_QUOTA_MINUTE_MS", "1"));
             let result = scenario.run_with_env(
                 &["secure", "harness", "codex", "email", "me@example.com"],
-                &resend_env(&resend),
+                &env,
             );
             assert_eq!(result.code, Some(1), "{}", result.stderr);
             assert!(result.stderr.contains(diagnostic), "{}", result.stderr);

From 7ca963dcc19f02ab688efd716df1447f610b20f3 Mon Sep 17 00:00:00 2001
From: Jacob Stephens <jstephens@etadventures.com>
Date: Wed, 11 Nov 2026 00:55:38 -0500
Subject: [PATCH 8/8] Keep pre-audit GitHub diagnostics off the Command log and
 notification

---
 src/command.rs             |   8 +++
 src/logs/command_record.rs |  14 +++--
 src/notification.rs        |   6 ++-
 src/run_ending.rs          |   9 +++-
 tests/security_run.rs      | 106 +++++++++++++++++++++++++++++++++++++
 5 files changed, 135 insertions(+), 8 deletions(-)

diff --git a/src/command.rs b/src/command.rs
index 97ecc59f7..a53c467fa 100644
--- a/src/command.rs
+++ b/src/command.rs
@@ -190,6 +190,14 @@ impl Started {
             | Ending::Security(_)
             | Ending::Skipped(_) => None,
         };
+        // progress::step keeps lines in a Command log a Quota wait may already
+        // have opened. The raw pre-audit diagnostic stays on the terminal.
+        if let Some(diagnostic) = account
+            .pre_audit_failure
+            .and(account.ended.as_ref().err().map(|cause| cause.full()))
+        {
+            eprintln!("{diagnostic}");
+        }
         let code = account.show(elapsed);
         if let Some(notification) = self.notification {
             notification.finish(&account);
diff --git a/src/logs/command_record.rs b/src/logs/command_record.rs
index f097166a6..0441ce48e 100644
--- a/src/logs/command_record.rs
+++ b/src/logs/command_record.rs
@@ -365,11 +365,15 @@ impl CommandRecord {
     ) {
         self.ended_at = Some(outside.now().to_rfc3339());
         self.outcome = Some(account.outcome.into());
-        self.cause = account
-            .ended
-            .as_ref()
-            .err()
-            .map(|cause| cause.full().into());
+        // A Quota wait may already have opened this record. Pre-audit GitHub
+        // diagnostics stay on the terminal; the record keeps the fixed cause.
+        self.cause = account.pre_audit_failure.map(str::to_owned).or_else(|| {
+            account
+                .ended
+                .as_ref()
+                .err()
+                .map(|cause| cause.full().to_owned())
+        });
         self.pull_request = account.pr_url.map(String::from);
         self.security_findings_waiting = account.security_findings_waiting;
         self.security_findings = account.security_findings.unwrap_or_default().to_vec();
diff --git a/src/notification.rs b/src/notification.rs
index c1d039216..f2e35cdcb 100644
--- a/src/notification.rs
+++ b/src/notification.rs
@@ -486,7 +486,11 @@ fn body(
     if let Some(log) = account.log {
         text += &format!("Session trace:  {}\n", log.display());
     }
-    if let Some(log) = command_log {
+    // A pre-audit notification uses the fixed cause. The Command log path
+    // stays on this machine: the email goes through a third party.
+    if account.pre_audit_failure.is_none()
+        && let Some(log) = command_log
+    {
         text += &format!("Command log:  {}\n", log.display());
     }
     if let Some(configured) = configured {
diff --git a/src/run_ending.rs b/src/run_ending.rs
index 59d2e21a3..176117385 100644
--- a/src/run_ending.rs
+++ b/src/run_ending.rs
@@ -586,10 +586,15 @@ impl Shown {
         match &account.ended {
             // Also on stderr, so the outcome shows even when stdout is captured.
             Ok(line) => steps.push(line.clone()),
-            Err(cause) => steps.push(cause.full().to_string()),
+            Err(cause) => steps.push(
+                account
+                    .pre_audit_failure
+                    .unwrap_or_else(|| cause.full())
+                    .to_string(),
+            ),
         }
         steps.extend(account.advice.iter().map(Advice::to_string));
-        if account.ended.is_err() {
+        if account.ended.is_err() && account.pre_audit_failure.is_none() {
             if let Some(log) = account.log {
                 steps.push(format!("{SESSION_LOG}{}", log.display()));
             }
diff --git a/tests/security_run.rs b/tests/security_run.rs
index ea8faade1..45397c9e3 100644
--- a/tests/security_run.rs
+++ b/tests/security_run.rs
@@ -4157,6 +4157,112 @@ fn pre_audit_github_failures_report_a_safe_cause_without_claiming_an_audit_ran()
     }
 }
 
+/// A within-cap Quota wait creates the Command record before pre-audit work
+/// finishes. The raw GitHub diagnostic still must not reach the Run
+/// notification, the Command log or the Command record: those outlive the
+/// process, and the notification is sent through a third party.
+#[test]
+fn within_cap_quota_wait_keeps_pre_audit_github_diagnostics_local() {
+    let scenario = Scenario::new();
+    scenario.user_config_is(&format!(
+        "[harness.codex]\nmodel = \"gpt-6.1-sol\"\neffort = \"high\"\n[logs]\ndir = {:?}\n",
+        scenario.path("custom-logs")
+    ));
+    scenario.gh_fails(
+        "api --paginate --jq .[] repos/acme/widgets/issues?state=open&labels=ready-for-agent&sort=created&direction=desc&per_page=100",
+    );
+    let reset = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap()
+        .as_secs()
+        + 1;
+    let mut github = scenario.gh_state();
+    github["failing_stderr"] = json!(
+        "GraphQL: API rate limit already exceeded for user ID PRIVATE-IDENTIFIER. token=PRIVATE-CREDENTIAL Private candidate write-up. Private provider/verifier diagnostic."
+    );
+    github["rate_limits"] = json!({
+        "core": {"remaining": 0, "reset": reset},
+        "graphql": {"remaining": 0, "reset": reset}
+    });
+    // The retry is past the cap, so the original diagnostic is what gets kept.
+    github["next_rate_limits"] = json!({
+        "core": {"remaining": 0, "reset": 4102444800u64},
+        "graphql": {"remaining": 0, "reset": 4102444800u64}
+    });
+    scenario.write_gh_state(&github);
+    let resend = ResendStandIn::replying(200, r#"{"id":"1"}"#);
+    let mut env = resend_env(&resend).to_vec();
+    env.push(("THIRDSHIFT_QUOTA_MINUTE_MS", "1"));
+    let result = scenario.run_with_env(
+        &["secure", "harness", "codex", "email", "me@example.com"],
+        &env,
+    );
+
+    assert_eq!(result.code, Some(1), "{}", result.stderr);
+    assert!(
+        result.stderr.contains("PRIVATE-CREDENTIAL"),
+        "the operator's stderr keeps the diagnostic: {}",
+        result.stderr
+    );
+    for root in ["custom-logs", "home/.thirdshift/logs"] {
+        let root = scenario.path(root);
+        if !root.exists() {
+            continue;
+        }
+        for body in log_bodies(&root) {
+            for private in [
+                "PRIVATE-IDENTIFIER",
+                "PRIVATE-CREDENTIAL",
+                "Private candidate write-up.",
+                "Private provider/verifier diagnostic.",
+            ] {
+                assert!(
+                    !body.contains(private),
+                    "{private} was stored under {}: {body}",
+                    root.display()
+                );
+            }
+        }
+    }
+    let (_subject, text) = the_one_notification(&resend);
+    assert!(
+        text.contains("Cause:        GitHub rate-limit exhaustion"),
+        "{text}"
+    );
+    for private in [
+        "PRIVATE-IDENTIFIER",
+        "PRIVATE-CREDENTIAL",
+        "Private candidate write-up.",
+        "Private provider/verifier diagnostic.",
+        "Command log:",
+        "token=",
+    ] {
+        assert!(
+            !text.contains(private),
+            "{private} reached the notification: {text}"
+        );
+    }
+}
+
+fn log_bodies(root: &std::path::Path) -> Vec<String> {
+    let mut bodies = Vec::new();
+    let mut pending = vec![root.to_path_buf()];
+    while let Some(dir) = pending.pop() {
+        let Ok(entries) = fs::read_dir(&dir) else {
+            continue;
+        };
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.is_dir() {
+                pending.push(path);
+            } else if let Ok(bytes) = fs::read(&path) {
+                bodies.push(String::from_utf8_lossy(&bytes).into_owned());
+            }
+        }
+    }
+    bodies
+}
+
 fn assert_pre_audit_response_dependency_cause(response: &str, diagnostic: &str) {
     let scenario = Scenario::new();
     let gh = scenario.path("bin/gh");