@tokenfactory/acc-runner 0.12.0 → 0.16.0

package/dist/failure-classifier.js

@@ -1,19 +1,46 @@
 /**
- * v0.48: classify a non-zero claude CLI exit into one of four categories
+ * v0.48: classify a non-zero claude CLI exit into one of five categories
  * so the watch loop can distinguish machine-level failures (which should
  * quarantine the runner) from genuine task errors (which count toward the
- * task's retry budget).
+ * task's retry budget) and from a spent capacity window (which should
+ * PAUSE, not quarantine).
  *
- * The four classes:
- *   usage_limit  — Claude/Anthropic plan limit or rate limit reached.
+ * The five classes:
+ *   capacity_exhausted — Claude/Anthropic session or usage limit reached
+ *                  (api_error_status 429 + a "resets <time>" message).
+ *                  A NEW v0.56 (T-56-1) retryable-infra class: capacity is
+ *                  a resource, not a failure. NEVER task_error and NEVER
+ *                  quarantine — the runner pauses claiming until the stated
+ *                  reset time (or a default backoff) then resumes with a
+ *                  single probe. Root cause of the 2026-06-05 brownout.
+ *   usage_limit  — A hard Claude/Anthropic plan limit that will NOT reset
+ *                  on its own soon (out of credits, monthly spend cap,
+ *                  quota exhausted). Quarantine is still the right response
+ *                  — an operator has to top up or wait out the billing cycle.
  *   auth_expired — API key invalid or session expired on the user's machine.
  *   env_broken   — Host-side environment failure (dyld, missing binary, OOM).
  *                  Root cause of the pd36 claim-and-fail storm (INCIDENT_2026-06-02).
  *   task_error   — Everything else; genuine task-level failure.
  *
- * Only task_error counts toward a task's retry budget. The other three
- * trigger runner quarantine in watch.ts.
+ * Only task_error counts toward a task's retry budget. usage_limit /
+ * auth_expired / env_broken trigger runner quarantine in watch.ts;
+ * capacity_exhausted triggers the pause/resume path instead.
  */
+// v0.56 (T-56-1): signatures of a SPENT-BUT-RECOVERABLE capacity window —
+// the session/usage limit Claude resets on a clock (vs. usage_limit below,
+// which is a hard billing wall). These must stay disjoint from the
+// usage_limit patterns so the live 2026-06-05 signature
+// ("You've hit your session limit - resets 3:20pm (Asia/Calcutta)")
+// routes to pause, while "out of credits" / "monthly spend limit" still
+// route to quarantine. The authoritative signal is api_error_status 429 in
+// the result JSON; these message patterns are the fallback when the runner
+// only has plain text (older claude, or the JSON envelope was not emitted).
+const CAPACITY_PATTERNS = [
+    /hit your (?:session|usage|account) limit/i,
+    /session limit/i,
+    /(?:session|usage|account|limit).*resets?\b/i,
+    /resets?\s+(?:at\s+)?\d{1,2}(?::\d{2})?\s*(?:am|pm)/i,
+];
 const USAGE_LIMIT_PATTERNS = [
     /usage limit/i,
     /you have reached the maximum number of tokens/i,
@@ -65,6 +92,129 @@ const FAST_EXIT_MAX_OUTPUT_BYTES = 100;
 function matchesAny(text, patterns) {
     return patterns.some((p) => p.test(text));
 }
+/**
+ * v0.56 (T-56-1): pull `api_error_status` out of claude's
+ * `--output-format=json` envelope. On a session/usage limit the CLI exits
+ * 1 with a JSON object carrying `{ "is_error": true, "api_error_status":
+ * 429, "result": "You've hit your session limit - resets 3:20pm
+ * (Asia/Calcutta)" }`. Returns the numeric status when present, else null.
+ * Kept self-contained (a local parse, no cost-pricing import) so the
+ * classifier stays a pure (strings) → class function for unit tests.
+ */
+export function parseApiErrorStatus(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed.startsWith("{"))
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        const status = parsed?.api_error_status;
+        if (typeof status === "number")
+            return status;
+        if (typeof status === "string" && /^\d+$/.test(status))
+            return Number(status);
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+const RESET_TIME_RE = /resets?\s+(?:at\s+|by\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*(?:\(([^)]+)\))?/i;
+function tzDateParts(instant, tz) {
+    const dtf = new Intl.DateTimeFormat("en-US", {
+        timeZone: tz,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hour12: false,
+    });
+    const map = {};
+    for (const p of dtf.formatToParts(instant)) {
+        if (p.type !== "literal")
+            map[p.type] = p.value;
+    }
+    // Intl can emit "24" for midnight in hour12:false mode; normalise to 0.
+    const hour = Number(map.hour) === 24 ? 0 : Number(map.hour);
+    return {
+        year: Number(map.year),
+        month: Number(map.month),
+        day: Number(map.day),
+        hour,
+        minute: Number(map.minute),
+        second: Number(map.second),
+    };
+}
+/** Offset (ms) of `tz` relative to UTC at the given instant (east = positive). */
+function zoneOffsetMs(instant, tz) {
+    const p = tzDateParts(instant, tz);
+    const asUtc = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second);
+    return asUtc - instant;
+}
+/** Resolve a wall-clock Y-M-D H:M in `tz` to a UTC epoch (one DST refinement). */
+function wallClockToUtc(year, month, day, hour, minute, tz) {
+    const guess = Date.UTC(year, month - 1, day, hour, minute, 0);
+    let instant = guess - zoneOffsetMs(guess, tz);
+    const off2 = zoneOffsetMs(instant, tz);
+    const refined = guess - off2;
+    if (refined !== instant)
+        instant = refined;
+    return instant;
+}
+/**
+ * v0.56 (T-56-1): parse the reset time Claude states when it pauses a
+ * session ("...resets 3:20pm (Asia/Calcutta)") into an absolute epoch
+ * (ms). The runner schedules its capacity resume off this so it wakes
+ * exactly when the window reopens rather than guessing a fixed backoff.
+ *
+ *   - 12h ("3:20pm") and 24h ("15:20") clock forms are both accepted.
+ *   - A parenthetical IANA zone ("(Asia/Calcutta)") is honoured; without
+ *     one the time is read in the runner's local zone.
+ *   - The soonest FUTURE occurrence wins: a stated time already past today
+ *     rolls to tomorrow.
+ *
+ * Returns null when no reset time is present or the zone is unparseable —
+ * the caller then falls back to a default backoff.
+ */
+export function extractResetTime(text, now = Date.now()) {
+    if (!text)
+        return null;
+    const m = RESET_TIME_RE.exec(text);
+    if (!m)
+        return null;
+    let hour = Number(m[1]);
+    const minute = m[2] ? Number(m[2]) : 0;
+    const ampm = m[3]?.toLowerCase();
+    const tz = m[4]?.trim();
+    if (Number.isNaN(hour) || hour > 23 || minute > 59)
+        return null;
+    if (ampm === "pm" && hour < 12)
+        hour += 12;
+    if (ampm === "am" && hour === 12)
+        hour = 0;
+    try {
+        if (tz) {
+            const today = tzDateParts(now, tz);
+            let instant = wallClockToUtc(today.year, today.month, today.day, hour, minute, tz);
+            if (instant <= now) {
+                const tomorrow = tzDateParts(now + 24 * 3_600_000, tz);
+                instant = wallClockToUtc(tomorrow.year, tomorrow.month, tomorrow.day, hour, minute, tz);
+            }
+            return instant;
+        }
+        const local = new Date(now);
+        local.setHours(hour, minute, 0, 0);
+        let instant = local.getTime();
+        if (instant <= now)
+            instant += 24 * 3_600_000;
+        return instant;
+    }
+    catch {
+        // Unknown/garbled IANA zone — let the caller apply its default backoff.
+        return null;
+    }
+}
 /**
  * Classify a non-zero claude exit.
  *
@@ -84,6 +234,18 @@ export function classifyClaudeExit(exitCode, stderr, stdout, durationMs) {
         };
     }
     const combined = `${stderr}\n${stdout}`;
+    // v0.56 (T-56-1): capacity check FIRST so the recoverable session/usage
+    // window routes to pause, not quarantine. Authoritative signal is the
+    // result JSON's api_error_status 429; the message patterns are the
+    // plain-text fallback. Disjoint from USAGE_LIMIT_PATTERNS below, which
+    // stay quarantine-worthy (hard billing walls).
+    if (parseApiErrorStatus(stdout) === 429 || matchesAny(combined, CAPACITY_PATTERNS)) {
+        return {
+            exitCode,
+            class: "capacity_exhausted",
+            detail: "Claude session/usage capacity reached (429) — runner will pause until reset",
+        };
+    }
     if (matchesAny(combined, USAGE_LIMIT_PATTERNS)) {
         return {
             exitCode,
@@ -117,6 +279,10 @@ export function classifyClaudeExit(exitCode, stderr, stdout, durationMs) {
             exitCode,
             class: "env_broken",
             detail: `claude exited ${exitCode ?? "signal"} in ${durationMs}ms with empty output (env_broken heuristic)`,
+            // v0.53 T-53-4: flag the heuristic origin so the task-runner applies
+            // the "retry once, quarantine only on 2 consecutive" tune rather than
+            // benching the machine on a single instant-empty blip.
+            heuristic: true,
         };
     }
     return {

package/dist/failure-classifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"failure-classifier.js","sourceRoot":"","sources":["../src/failure-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAcH,MAAM,oBAAoB,GAAa;IACrC,cAAc;IACd,gDAAgD;IAChD,sBAAsB;IACtB,iBAAiB;IACjB,sBAAsB;IACtB,aAAa;IACb,iBAAiB;IACjB,sBAAsB;IACtB,oCAAoC;CACrC,CAAC;AAEF,MAAM,qBAAqB,GAAa;IACtC,kBAAkB;IAClB,yBAAyB;IACzB,oBAAoB;IACpB,eAAe;IACf,0CAA0C;IAC1C,mBAAmB;IACnB,yCAAyC;IACzC,oBAAoB;IACpB,uBAAuB;IACvB,gBAAgB;CACjB,CAAC;AAEF,yEAAyE;AACzE,4EAA4E;AAC5E,2EAA2E;AAC3E,MAAM,mBAAmB,GAAa;IACpC,8BAA8B;IAC9B,qBAAqB;IACrB,kBAAkB;IAClB,oCAAoC;IACpC,QAAQ;IACR,aAAa;IACb,qBAAqB;IACrB,SAAS;IACT,eAAe;IACf,oBAAoB;IACpB,4BAA4B;IAC5B,0BAA0B;IAC1B,WAAW;IACX,SAAS;IACT,6BAA6B;CAC9B,CAAC;AAEF,kEAAkE;AAClE,sEAAsE;AACtE,4EAA4E;AAC5E,MAAM,YAAY,GAAG,KAAK,CAAC;AAC3B,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAEvC,SAAS,UAAU,CAAC,IAAY,EAAE,QAAkB;IAClD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAuB,EACvB,MAAc,EACd,MAAc,EACd,UAAmB;IAEnB,mEAAmE;IACnE,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;QACrB,OAAO;YACL,QAAQ;YACR,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,4CAA4C;SACrD,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,GAAG,MAAM,KAAK,MAAM,EAAE,CAAC;IAExC,IAAI,UAAU,CAAC,QAAQ,EAAE,oBAAoB,CAAC,EAAE,CAAC;QAC/C,OAAO;YACL,QAAQ;YACR,KAAK,EAAE,aAAa;YACpB,MAAM,EAAE,wCAAwC;SACjD,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,QAAQ,EAAE,qBAAqB,CAAC,EAAE,CAAC;QAChD,OAAO;YACL,QAAQ;YACR,KAAK,EAAE,cAAc;YACrB,MAAM,EAAE,6DAA6D;SACtE,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,CAAC,QAAQ,EAAE,mBAAmB,CAAC,EAAE,CAAC;QAC9C,OAAO;YACL,QAAQ;YACR,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,mDAAmD;SAC5D,CAAC;IACJ,CAAC;IAED,kEAAkE;IAClE,wEAAwE;IACxE,qEAAqE;IACrE,qEAAqE;IACrE,IACE,UAAU,KAAK,SAAS;QACxB,UAAU,GAAG,YAAY;QACzB,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;QAC1B,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,0BAA0B,EACjD,CAAC;QACD,OAAO;YACL,QAAQ;YACR,KAAK,EAAE,YAAY;YACnB,MAAM,EAAE,iBAAiB,QAAQ,IAAI,QAAQ,OAAO,UAAU,6CAA6C;SAC5G,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ;QACR,KAAK,EAAE,YAAY;QACnB,MAAM,EAAE,iBAAiB,QAAQ,IAAI,QAAQ,uBAAuB;KACrE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"failure-classifier.js","sourceRoot":"","sources":["../src/failure-classifier.ts"],"names":[],"mappings":"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"}

package/dist/git.d.ts

@@ -6,6 +6,21 @@ export interface GitRunner {
     push(repoPath: string, branch: string): Promise<void>;
     /** True when the working tree has no uncommitted changes. */
     isClean(repoPath: string): Promise<boolean>;
+    /**
+     * v0.53 T-53-4: the EARLIEST commit on `branch` that is not reachable
+     * from `baseRef` — i.e. the first commit the task produced on its branch
+     * — as `{ sha, ts }` where `ts` is the committer date (ISO-8601), or
+     * null when the branch has no commits ahead of the base. Powers the
+     * `task.first_commit` SLO signal (when coding actually started).
+     *
+     * Optional on the interface so existing GitRunner test stubs that omit
+     * it keep compiling; the default implementation below provides it and
+     * the task-runner guards the call with `?.`.
+     */
+    firstCommit?(repoPath: string, baseRef: string, branch: string): Promise<{
+        sha: string;
+        ts: string;
+    } | null>;
 }
 export type PushErrorKind = "transient" | "terminal";
 /**

package/dist/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,kBAAkB,QAAsC,CAAC;AAEtE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEpE;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7C;AAMD,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA0B7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,wCAAwC;IACxC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAQD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC3B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,eAAO,MAAM,GAAG,EAAE,SAiBjB,CAAC"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,kBAAkB,QAAsC,CAAC;AAEtE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEpE;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,WAAW,CAAC,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CAChD;AAMD,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CA0B7D;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,wCAAwC;IACxC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAQD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAC3B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,eAAO,MAAM,GAAG,EAAE,SAkCjB,CAAC"}

package/dist/git.js

@@ -104,5 +104,24 @@ export const git = {
         const { stdout } = await run(repoPath, ["status", "--porcelain"]);
         return stdout.trim().length === 0;
     },
+    async firstCommit(repoPath, baseRef, branch) {
+        // `--reverse` lists oldest→newest so the first line is the earliest
+        // commit on `branch` not reachable from `baseRef`. %H = full sha,
+        // %cI = committer date in strict ISO-8601. A tab separator survives
+        // both fields cleanly (commit dates never contain tabs).
+        const { stdout } = await run(repoPath, [
+            "log",
+            "--reverse",
+            "--format=%H%x09%cI",
+            `${baseRef}..${branch}`,
+        ]);
+        const firstLine = stdout.split(/\r?\n/).find((l) => l.trim().length > 0);
+        if (!firstLine)
+            return null;
+        const [sha, ts] = firstLine.split("\t");
+        if (!sha)
+            return null;
+        return { sha: sha.trim(), ts: (ts ?? "").trim() };
+    },
 };
 //# sourceMappingURL=git.js.map

package/dist/git.js.map

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

package/dist/github-client.d.ts

@@ -0,0 +1,133 @@
+/**
+ * v0.53 T-53-4 — runner-side, budget-aware GitHub REST client.
+ *
+ * A port of the api/ side's `api/_lib/github-client.ts` (T-52-4) into the
+ * runner package. The runner CANNOT import api/ code (separate build, no
+ * shared module graph), so the pattern is reproduced here. The three
+ * behaviours match the server client 1:1:
+ *
+ *   1. Quota tracking — x-ratelimit-remaining / x-ratelimit-reset per
+ *      resource (core, search, graphql, …) from every response, surfaced
+ *      via getQuotaSnapshot() for `acc-runner doctor`.
+ *
+ *   2. Secondary-limit backoff — a 429, or a 403 carrying retry-after /
+ *      x-ratelimit-remaining: 0, is a rate-limit response, not an answer.
+ *      The client sleeps once (retry-after if given, else an exponential
+ *      base, both jittered, capped at MAX_BACKOFF_MS) and retries once. A
+ *      second rate-limit response — or a retry-after beyond the cap —
+ *      surfaces as a typed RateLimitedError.
+ *
+ *   3. Per-task-execution soft budget — runTask arms a budget at the top
+ *      of a task (startTaskGithubBudget) and disarms it in its finally
+ *      (endTaskGithubBudget). Once the budget is spent, every further
+ *      githubFetch throws GithubBudgetExceededError WITHOUT hitting the
+ *      network. The caller treats this as a CLEAN, RETRYABLE infra failure
+ *      — NOT a code failure: it never reaches classifyClaudeExit, so the
+ *      runner is never quarantined for exhausting its GitHub budget.
+ *
+ * ── Coverage note (READ THIS) ──────────────────────────────────────────
+ * As of v0.53 the runner makes ALL of its GitHub calls through the `gh`
+ * CLI (see gh.ts, runtime/conflict-resolver.ts, runtime/rework.ts,
+ * runtime/reviewer.ts). Those `gh`/`gh api` invocations are SEPARATE
+ * processes with their own rate-limit handling and are out of scope for
+ * this client — they remain UNCOVERED by the budget/backoff here. This
+ * module is the sanctioned wrapper for any future *direct* REST call the
+ * runner adds (`fetch` against api.github.com); routing such calls through
+ * githubFetch is what keeps them budget- and rate-limit-aware.
+ *
+ * Reference: api/_lib/github-client.ts, planning/ACC_WORKFLOW_GAP_ANALYSIS.md §G13.
+ */
+/** Soft per-task-execution call budget. */
+export declare const DEFAULT_TASK_GITHUB_BUDGET = 50;
+/**
+ * Longest single backoff sleep. A secondary-limit retry-after can be 60s+;
+ * sleeping that long inside a task run wastes wall-clock the operator is
+ * paying for, so anything above the cap skips the retry and throws
+ * RateLimitedError instead.
+ */
+export declare const MAX_BACKOFF_MS = 15000;
+/** Base for the exponential backoff when GitHub sends no retry-after. */
+export declare const BASE_BACKOFF_MS = 2000;
+/**
+ * Typed rate-limit failure: GitHub said "back off" twice in a row (or
+ * asked for a longer wait than we can afford). A rate-limit storm is then
+ * diagnosable instead of looking like random github_http_403 noise. This
+ * is a RETRYABLE INFRA failure — see isRetryableGithubError.
+ */
+export declare class RateLimitedError extends Error {
+    readonly status: number;
+    readonly resource: string | null;
+    /** ISO timestamp the quota window resets at, when GitHub said. */
+    readonly reset_at: string | null;
+    readonly retry_after_s: number | null;
+    constructor(opts: {
+        status: number;
+        resource: string | null;
+        reset_at: string | null;
+        retry_after_s: number | null;
+    });
+}
+/**
+ * Soft-budget exhaustion. NOT a code failure: the task simply did as much
+ * direct GitHub work as one task execution is allowed. The caller should
+ * surface it as a clean, RETRYABLE infra failure and NEVER feed it to the
+ * claude-exit classifier (which would quarantine the runner).
+ */
+export declare class GithubBudgetExceededError extends Error {
+    readonly used: number;
+    readonly budget: number;
+    constructor(used: number, budget: number);
+}
+/**
+ * v0.53 T-53-4: both client failure modes are retryable infra conditions,
+ * not task/code failures. The contract the runner relies on: an error for
+ * which this returns true must surface as `phase: "github"` / retryable and
+ * MUST NOT set `quarantine_cause` — i.e. it is classifier-neutral and never
+ * benches the runner.
+ */
+export declare function isRetryableGithubError(err: unknown): boolean;
+interface ResourceQuota {
+    remaining: number | null;
+    /** ISO timestamp. */
+    reset_at: string | null;
+}
+export interface GithubQuotaSnapshot {
+    /** Lowest remaining across observed resources (the binding constraint). */
+    remaining: number | null;
+    /** Reset time of that lowest-remaining resource. */
+    reset_at: string | null;
+    /** Direct REST calls made since the last startTaskGithubBudget(). */
+    used_this_task: number;
+    /** Per-resource view (core, search, …) as reported by GitHub headers. */
+    resources: Record<string, ResourceQuota>;
+}
+/**
+ * Begin a budgeted task execution: resets the per-task counter and arms the
+ * soft budget. runTask calls this at the top of a task; the explicit reset
+ * also re-baselines a long-lived watch process between tasks.
+ */
+export declare function startTaskGithubBudget(budget?: number): void;
+/**
+ * End a budgeted task execution: disarms the soft budget so any direct REST
+ * call made OUTSIDE a task run (e.g. doctor) is unbudgeted. Idempotent.
+ */
+export declare function endTaskGithubBudget(): void;
+export declare function getQuotaSnapshot(): GithubQuotaSnapshot;
+/** Test seam: wipe quota/budget state between unit tests. */
+export declare function resetGithubClientStateForTests(): void;
+/** Injection seams for unit tests; production callers never pass this. */
+export interface GithubFetchDeps {
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    /** Returns [0, 1); defaults to Math.random. Drives backoff jitter. */
+    random?: () => number;
+}
+/**
+ * Authenticated GitHub REST fetch. The caller supplies whatever token is
+ * appropriate (the runner uses the operator's own gh/git credentials for
+ * CLI calls; a direct REST consumer would pass a token it already holds).
+ * An empty token sends an anonymous request rather than `Bearer <empty>`.
+ */
+export declare function githubFetch(url: string, token: string, init?: RequestInit, deps?: GithubFetchDeps): Promise<Response>;
+export {};
+//# sourceMappingURL=github-client.d.ts.map

package/dist/github-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-client.d.ts","sourceRoot":"","sources":["../src/github-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,2CAA2C;AAC3C,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAS,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,eAAe,OAAQ,CAAC;AAErC;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;gBAE1B,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;KAC9B;CAYF;AAED;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,qBAAqB;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC1C;AAOD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,MAAmC,GAAG,IAAI,CAGvF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,wBAAgB,gBAAgB,IAAI,mBAAmB,CAkBtD;AAED,6DAA6D;AAC7D,wBAAgB,8BAA8B,IAAI,IAAI,CAIrD;AA6CD,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAMD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,WAAgB,EACtB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,QAAQ,CAAC,CAwCnB"}