diff --git a/README.md b/README.md index dc5f041e..0c594a8d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@

Clockgrove Pendulum

-

Label a GitHub issue, walk away, come back to a reviewed pull request.

+

Hand off a GitHub issue, walk away, come back to a reviewed pull request.

Release @@ -12,7 +12,7 @@ License: MIT

-Clockgrove Pendulum turns a GitHub issue into a pull request (PR), using the coding agent you choose: Claude Code, Codex or GitHub Copilot CLI. You write what you want and what "done" means, and label the issue `pendulum:objective`. The coding agent plans and builds the change, Pendulum opens the PR, and a separate agent run reviews it. Then you merge it yourself, or, with auto-merge on, Pendulum merges it once your required CI checks pass. +Clockgrove Pendulum turns a GitHub issue into a pull request (PR), using the coding agent you choose: Claude Code, Codex or GitHub Copilot CLI. You write what you want and what "done" means. Keep `pendulum:objective` on the issue and remove `pendulum:draft` when it is ready to run. The coding agent plans and builds the change, Pendulum opens the PR, and a separate agent run reviews it. Then you merge it yourself, or, with auto-merge on, Pendulum merges it once your required CI checks pass. It is for maintainers of a GitHub repository with CI on pull requests who want to hand whole features to a coding agent, from a change that fits in one PR to an epic delivered as a series of PRs, and keep their own issues, checks and merge queue as the workflow. It runs on GitHub Actions or on your own machine and keeps all its state in GitHub, so there is no server or database to host. @@ -156,7 +156,7 @@ The session writes the issue in the shape Pendulum reads and shows it to you. It - No new dependencies. ``` -It asks whether to start it now (it adds the `pendulum:objective` label), save it as a draft issue (`pendulum:draft`, which Pendulum never runs), or keep discussing. Start it. +It asks whether to start it now, save it as a draft issue, or keep discussing. It files the issue with both `pendulum:objective` and `pendulum:draft`. Start it by letting the session remove `pendulum:draft`. ### 5. Watch it, then merge @@ -177,7 +177,7 @@ Runs take from a few minutes to a few hours. When its run ends, a finish card on ## How it works -1. **You label an issue `pendulum:objective`.** The issue is now an Objective, and its text is the whole specification. +1. **You file an Objective and take it out of Draft.** The issue keeps `pendulum:objective` throughout its lifecycle. When you remove `pendulum:draft`, it can enter the queue. Its text is the whole specification. 2. **A worker plans and builds.** The worker is the coding agent, on a strong model. It writes a plan, which Pendulum posts on the issue, hands the plan's items to implementer sub-agents, usually on a cheaper model and side by side where they touch separate files, then integrates their work in its own checkout, and Pendulum opens a PR. A large Objective arrives as a series of PRs, one open at a time, each part starting once the one before has merged (up to six by default, `max_parts`). 3. **Your CI decides.** The worker waits for your required checks. When one fails, it keeps fixing while each pass makes progress, within the job's spending and time limits, then the Objective is Blocked. 4. **A reviewer comments.** The reviewer is a separate agent run that compares the change with the issue and judges each Acceptance entry. The worker must answer each comment: fix it, or explain why the issue or the repository's rules already settle it. @@ -232,7 +232,7 @@ The worker asks you something only when the work depends on a decision that shou | "Add team invitations." | Goal: a workspace admin can invite people by email, and an invitee joins with one link. Acceptance: an invitation emails a link valid for 7 days; following it after sign-up adds the user to that workspace as a member; an expired or used link shows an error page; admins can list and revoke pending invitations; tests cover each path. Context: use the existing mailer; the sign-up form does not change. | | "Rebuild reporting." | Split the epic where it has a natural order: one Objective for the report export API, and one for the page that uses it, marked as blocked by the first. | -**For an epic with an order,** file several Objectives and link them with GitHub's issue dependencies (blocked by), added before an issue gets its `pendulum:objective` label: Pendulum starts each one once the issues it waits on are closed. Objectives without an order run side by side, up to `max_concurrent`; where two edit the same files, Pendulum rebases or holds back the later one so their changes do not collide ([Siblings that touch the same files](docs/USAGE.md#siblings-that-touch-the-same-files)). +**For an epic with an order,** file draft Objectives and link them with GitHub's issue dependencies (blocked by) before removing `pendulum:draft`. Pendulum starts each one once the issues it waits on are closed. Objectives without an order run side by side, up to `max_concurrent`. Where two edit the same files, Pendulum rebases or holds back the later one so their changes do not collide. [Siblings that touch the same files](docs/USAGE.md#siblings-that-touch-the-same-files) **Quick fixes are better as a direct PR.** Pendulum's planning, review and CI loop is worth its cost on feature-sized work. @@ -245,11 +245,11 @@ A run that goes well needs nothing from you. When one needs you, Pendulum does a | Situation | What you do | | --- | --- | | PR ready for review (auto-merge off) | Read it and merge it through your usual process. | -| **Blocked:** Pendulum could not finish, for example a check still fails or a spending limit was reached. One comment on the issue gives the reason, and the PR becomes a draft | Fix what the comment names, then label the issue `pendulum:objective` again. It resumes from its branch and PR. | +| **Blocked:** Pendulum could not finish, for example a check still fails or a spending limit was reached. One comment on the issue gives the reason, and the PR becomes a draft | Fix what the comment names. To resume from the existing branch and PR, add `pendulum:draft` if absent, then remove it once the previous run has stopped. | | **Question** in a draft PR: the work depends on a decision that should be yours, such as changing a public interface | Comment your decision on the issue or the PR, then mark the PR ready. | -| **Question** on the issue: the work needs another repository | Split it into one Objective per repository and label them, or comment how to do it in this repository alone: the next run picks up your answer, with no relabelling. | +| **Question** on the issue: the work needs another repository | Split it into one Objective per repository, or comment how to do it in this repository alone. The next run picks up that answer automatically. | | The work needs a workflow change | Pendulum leaves the change in a comment on the issue, labelled `pendulum:handover`. After the PR merges, ask "Apply the Pendulum workflow hand-over for Objective 12" ([Workflow changes](docs/USAGE.md#workflow-changes)). | -| Stop one Objective | Remove its `pendulum:objective` label, close its issue, or ask "Stop Pendulum Objective 12". A run in progress ends within about two minutes with its spend recorded; label it again to resume. | +| Stop one Objective | Add `pendulum:draft`, close its issue, or ask "Stop Pendulum Objective 12". A run in progress normally ends within two minutes with its spend recorded. To resume a held issue, remove Draft after the stop has settled. | | Start over from revised text | Label the issue `pendulum:restart`, or ask "Restart Pendulum Objective 12". The earlier PR is closed and its branch deleted. | | Stop everything | `gh workflow disable pendulum.yml` and cancel any runs in the Actions tab. In local mode, stop `pendulum serve` with Ctrl-C. With the cloud sandbox, also stop the Objective's sandboxes in your Vercel project. | diff --git a/bench/README.md b/bench/README.md index 34f32e3b..4a302e06 100644 --- a/bench/README.md +++ b/bench/README.md @@ -8,7 +8,7 @@ One row per Objective, read from the issue, the PR on `pendulum/`, the jo | Number | What the row says | Taken from | | --- | --- | --- | -| Walk-away | `yes`, or `no` with the first human action | Binary. The clock starts at the first `pendulum:objective` label. Any human push, comment, review, edit or draft/ready toggle on the branch or the issue after it breaks it. Edits of the issue and PR bodies are every edit GraphQL lists (`userContentEdits`), each by its own editor, so a later edit never hides an earlier one; Pendulum's own login's edits (the finish block on the merged PR's body) are not input. A person's `workflow_dispatch` or re-run of the Pendulum workflow (`--workflow`, default `pendulum.yml`) between the clock and the merge is input too: one whose jobs name Objectives counts for those, one that names none (a hand-started dispatcher tick) for every Objective in flight then. The adopter drill's own dispatch (`drill.mjs --dispatch`) is not input for the Objectives it filed: the drill records the run id GitHub returned on each of them (``, posted by the issue's author), and that run's first attempt, started by the same login, is the drill's. A re-run of it, or any other dispatch, still counts. A Blocked card (label or marker comment) is a miss; an answered Question is a miss, named as such, even when the answer is nowhere the scorer reads (Pendulum resumed after its Question). A workflow hand-over is scored by `--handover` (Workflow hand-over, below): by default it is normal work, an owner step shown apart, never input. `*[bot]` actors never count; `--bot LOGIN` adds another. Each human action is also split: *asked for* when it follows a Question, Blocked notice or review request Pendulum made and comes before Pendulum's next `pendulum:running` label, else *unprompted* (an owner's note, scope added after the label). The row carries `walkAway.interventions` (`asked`, `unprompted`, Pendulum's `requests`) and `walkAway.askedOnly`, walk-away counting only asked-for actions; the table shows both, and the line under it sums them. A merge that sat idle longer than the stall threshold (`--stall-minutes`, default 60) between Pendulum's acts is a stall, not a walk-away (`walkAway.stall`; every merged row carries `walkAway.longestIdleMinutes`): the rule, what counts as Pendulum's acts and as idle, is the pendulum-score skill's, in `plugin/skills/pendulum-score/reference.md` (Stalls). Pendulum's posts are told from a person's by their `` markers (in local mode Pendulum posts as the operator's login, and an unmarked comment, a label other than Pendulum's state labels and Pendulum's own `pendulum:handover` (applied with its hand-over comment on the issue or inside a run; removed inside a run only as its drop: the comment then carries no patch, or Pendulum applies the label again; any other removal is the person's mark that they applied it), or removing `pendulum:blocked` without a re-applied Objective label is the operator's). The PR closed by its merge, its branch deleted and the issue closed right after it are the merge's, never acts of their own. | +| Walk-away | `yes`, or `no` with the first human action | Binary. The clock starts at the first removal of `pendulum:draft`, or the first legacy Objective label applied outside Draft. Any human push, comment, review, edit or draft/ready toggle on the branch or the issue after it breaks it. Edits of the issue and PR bodies are every edit GraphQL lists (`userContentEdits`), each by its own editor, so a later edit never hides an earlier one; Pendulum's own login's edits (the finish block on the merged PR's body) are not input. A person's `workflow_dispatch` or re-run of the Pendulum workflow (`--workflow`, default `pendulum.yml`) between the clock and the merge is input too: one whose jobs name Objectives counts for those, one that names none (a hand-started dispatcher tick) for every Objective in flight then. The adopter drill's own dispatch (`drill.mjs --dispatch`) is not input for the Objectives it filed: the drill records the run id GitHub returned on each of them (``, posted by the issue's author), and that run's first attempt, started by the same login, is the drill's. A re-run of it, or any other dispatch, still counts. A Blocked card (label or marker comment) is a miss; an answered Question is a miss, named as such, even when the answer is nowhere the scorer reads (Pendulum resumed after its Question). A workflow hand-over is scored by `--handover` (Workflow hand-over, below): by default it is normal work, an owner step shown apart, never input. `*[bot]` actors never count; `--bot LOGIN` adds another. Each human action is also split: *asked for* when it follows a Question, Blocked notice or review request Pendulum made and comes before Pendulum's next `pendulum:running` label, else *unprompted* (an owner's note, scope added after the label). The row carries `walkAway.interventions` (`asked`, `unprompted`, Pendulum's `requests`) and `walkAway.askedOnly`, walk-away counting only asked-for actions; the table shows both, and the line under it sums them. A merge that sat idle longer than the stall threshold (`--stall-minutes`, default 60) between Pendulum's acts is a stall, not a walk-away (`walkAway.stall`; every merged row carries `walkAway.longestIdleMinutes`): the rule, what counts as Pendulum's acts and as idle, is the pendulum-score skill's, in `plugin/skills/pendulum-score/reference.md` (Stalls). Pendulum's posts are told from a person's by their `` markers (in local mode Pendulum posts as the operator's login, and an unmarked comment, a label other than Pendulum's state labels and Pendulum's own `pendulum:handover` (applied with its hand-over comment on the issue or inside a run; removed inside a run only as its drop: the comment then carries no patch, or Pendulum applies the label again; any other removal is the person's mark that they applied it), or removing `pendulum:blocked` without a re-applied Objective label is the operator's). The PR closed by its merge, its branch deleted and the issue closed right after it are the merge's, never acts of their own. | | Solution quality | `pending` with the pair for the judge | The judge's, never the scorecard's. With `--baseline REF` the row carries the `judge.mjs` command for the merged head against it; without, the owner's read of the merged diff. The row also carries a `grade-auto.mjs` command for the merged head against the PR's own base commit. Escapes found after merge go in `quality.escapes`: an issue labelled P1, opened after the merge, that references the merged PR is filled in, a P1 Objective filed to fix it included; add others by hand. `--append` keeps the hand-filled ones (once per `owner/name#N` they name) and replaces the found ones with this run's, so one whose P1 label was removed drops out. | | Operator minutes | `0`, a number, or `unknown` | `--minutes =` from a stopwatch; `0` on a clean merge; otherwise `unknown`, never estimated. A workflow hand-over's owner step has its own minutes, apart from these (Workflow hand-over, below). | | Cost | dollars with unit and basis | Claude: `usd` from `total_cost_usd` + `modelUsage` (sub-agents in). Codex: `usd` from its tokens priced from `plugin/scripts/lib/codex-prices.json` (the worker's own table), OpenAI's Standard rates as its pricing page and model pages give them, with the date and sources (a project on the Fast Service Tier pays 2× them (2.5× on gpt-5.5, 1.8× on gpt-5-mini), which Codex does not report); a model matches by its exact id (a provider prefix such as `openai/` stripped), a dated snapshot of it, or an alias OpenAI documents (`gpt-5.6`), else its runs are of unknown cost; a promotional rate (`until`) prices only a record that ended before that day, and a later one or one with no `ended` is of unknown cost (a stage's record ends with its latest pass or call); the tokens of a request over 272K input tokens are at the model's long-context rates, which the worker reads request by request from the thread's rollout into the record's `tokens.long`, and a record past 272K without that share (one the worker could not read, or written before it did) is of unknown cost for a model with such rates; a stage's Codex sub-agent threads (`subAgents` in its record) are priced at their own models and the rest of its tokens at the stage's; a run with no completed turn reports no tokens, so its dollars are unknown and its basis says that (`unknown: no Codex turn completed, so Codex reported no tokens`, the worker's record and the exit line alike), never a missing price; the unit stays `tokens` only while unpriced. Copilot: `usd` from the AI credits its `--usage-output-file` reports, at the run's `copilot_credit_usd` (GitHub's published $0.01 per credit by default), with the premium requests beside them (`cost.premiumRequests`, `cost.aiCredits`); an artifact without credits is of unknown cost. How the dollars are billed comes from each record's or spend line's `usdByBilling` and `billing`, which the worker writes on a positive sign only (docs/PLAN.md), never from the figure (`cost.usdByBilling`; a re-priced Codex part takes its record's `billing`): billed per use on a key is the bare figure; Claude Code's `total_cost_usd` or Codex tokens on a subscription are "API-equivalent at list prices, on the subscription"; Copilot's are "Copilot AI credits, billed to the seat"; anything else is "billing not recorded"; an Objective that mixes them shows each part in the cell and the basis. A record from before Pendulum named billing carries none and reads bare. Reviewer artifacts are summed with the worker's. A stage that ran in a cloud sandbox carries the vendor's cost in its record (`vendor`, at the vendor's dated list rates, docs/ADAPTERS.md "Vendor cost"); it is summed beside the model's dollars as `cost.vendorUsd`, with `cost.totalUsd` for both, and the cell reads `model + sandbox = total`; a stage whose usage the vendor did not report is a run of unknown cost there, never its session's ceiling. The dollars are every stage's on every route, each once: the usage artifacts (GitHub Actions, the cloud sandbox) and the `` lines in Pendulum's own progress comments (local mode uploads no artifact), as the worker priced them; a progress comment of a record's own stage (work or review) that the record names counts as that record, whatever order the records come in: by its `progressRun` (the comment's key; null when the stage had no comment), else, for a record from before `progressRun`, by the sandbox stage's claim (`vendor.claim`, the key's `-`) or the workflow run that uploaded the artifact (the key's `` or `-`), else, for a local `result.json` with no `progressRun` field on an account, that account's comments of its stage. A record Pendulum wrote for a stage whose own process wrote none (`standIn`) gives way to the stage's comment, or, when the stage's own record took it, gives that record its sandbox cost and is dropped. A record that names no comment counts beside the comments, but never doubles a figure: one with no `progressRun` field (a local `result.json` from before records named their comment) beside an unnamed comment of its stage with dollars may be that stage, so its dollars are unknown there (`unmatched`) and the comment's count once. The cost of this exactness is an unknown run, never a known figure twice: such a record and its comment show the comment's dollars plus one run of unknown cost, and a local stage killed before it wrote its `result.json`, scored with `--usage`, adds a run of unknown cost beside its comment. Beside artifacts, a stage's comment with no artifact and no spend line (an artifact that expired) is a run of unknown cost. A relayed worker key's dollars are inside each line's `usd` (broken out as `workerKeyUsd`, counted once), and a stage without a line is a run of unknown cost; a line's `usdUnknown` (runs whose spend no harness or vendor reported: killed, crashed or hung passes, a zeroed result, a model with no price row) is carried into the total; a sandbox stage's vendor dollars are the spend line of its vendor comment (``), beside its progress comment's. AI Gateway decision calls: a stage's are in its record's `usd` (apart as `gatewayDecisionUsd`, kept as the gateway reported them when a Codex stage's tokens are priced again), and those made outside a stage (the dispatcher's, the launcher's, a local loop's answer, comment, edit and lapse checks) are the `` lines in Pendulum's own comments on the issue (a notice or record the check wrote, or a role's `` comment), added to the row on every route, as `api` (billed to the gateway key). Spend that a harness or vendor did not report is shown as unknown, as "plus N runs of unknown cost" beside the known dollars (`cost.usdUnknown`, its reasons in the basis), never as $0, an estimate or a bound; it is not counted against `max_usd` or `daily_usd` either, so a cap can be exceeded by it. Runner minutes and wall time (label to merge) sit beside it; wall time is never alone. | @@ -90,7 +90,7 @@ node bench/drill.mjs --repo OWNER/SCRATCH --set medium --count 5 --dispatch # node bench/drill.mjs --repo OWNER/SCRATCH --set conflict --dispatch # conflict: two Objectives that edit one README section, so the second is sent back to rebase ``` -A Question or Blocked exit ends the drill's wait for that Objective. The drill then waits (`--usage-wait-minutes`, default 10) for the usage artifact of each stage Pendulum ran, which can land after the label, downloads every one, and scores Blocked and merged Objectives alike; an artifact that never came is named in the report's `usageMissing` and its row says `missing: usage artifact`. An Objective still running when `--wait-minutes` runs out is not waited for, but its finished stages' artifacts are downloaded and scored, and its running stage is named in `usageMissing` as `(still running)`: its dollars are a floor. The drill files Objectives on a scratch repository (never Pendulum's own, never a product repository), lets the Action take them, waits, and scores them. The medium set is the instrument for changes to the worker's skills; the reviewer's is `bench/review-replay.mjs` against the private replay set. +A Question or Blocked exit ends the drill's wait for that Objective. The drill then waits (`--usage-wait-minutes`, default 10) for the usage artifact of each stage Pendulum ran, which can land after the label, downloads every one, and scores Blocked and merged Objectives alike; an artifact that never came is named in the report's `usageMissing` and its row says `missing: usage artifact`. An Objective still running when `--wait-minutes` runs out is not waited for, but its finished stages' artifacts are downloaded and scored, and its running stage is named in `usageMissing` as `(still running)`: its dollars are a floor. The drill files both labels on a scratch repository (never Pendulum's own, never a product repository) and removes Draft when each issue is ready. It follows the dispatcher, waits, and scores the Objectives. The medium set is the instrument for changes to the worker's skills; the reviewer's is `bench/review-replay.mjs` against the private replay set. ## Sandbox check diff --git a/bench/drill.mjs b/bench/drill.mjs index 6984a59c..185fb9fc 100644 --- a/bench/drill.mjs +++ b/bench/drill.mjs @@ -2,7 +2,7 @@ /** * `node bench/drill.mjs --repo OWNER/NAME --count N`: the adopter drill. Files N small, * fresh Objectives on a scratch repository (each a one-function addition over the - * repository's `greet`, named uniquely), lets the Action take them (the opened-issue tick, + * repository's `greet`, named uniquely). Removes Draft after filing so the Action takes them (the Draft-removal tick, * or `--dispatch` to fire one manually), waits until every one is closed or Blocked, then * scores them with bench/score.mjs. Exit 0 when every Objective merged with no human * input; 1 otherwise; 64 usage. @@ -17,7 +17,7 @@ * unit and database tests, suffixed so repeated runs never collide; every one changes * the scratch adopter alone * --count N Objectives to file (default 2 for small, 5 for medium) - * --dispatch dispatch pendulum.yml after filing (when the opened tick is not trusted); the run's id + * --dispatch dispatch pendulum.yml after activation (when the label tick is not trusted); the run's id * is recorded on each filed Objective, so the scorer reads it as the drill's, not input * --local also label each Objective pendulum:local, so a local loop (plugin/scripts/local.mjs serve) * takes it and the Actions path leaves it alone @@ -40,6 +40,7 @@ import { join, resolve } from "node:path"; import { parseArgs } from "node:util"; import { promisify } from "node:util"; import { awaitUsage } from "./lib/collect.mjs"; +import { DRAFT_LABEL } from "../plugin/scripts/lib/activation.mjs"; import { ghApi } from "./lib/gh.mjs"; import { mediumObjectives } from "./lib/medium.mjs"; import { drillRecord } from "./lib/objective.mjs"; @@ -134,14 +135,15 @@ for (const o of objectives) { writeFileSync(file, o.body); let url; try { - url = await gh("issue", "create", "-R", repo, "--title", o.title, "--body-file", file, "--label", "pendulum:objective", "--label", "P1", ...(values.local ? ["--label", "pendulum:local"] : [])); + url = await gh("issue", "create", "-R", repo, "--title", o.title, "--body-file", file, "--label", "pendulum:objective", "--label", DRAFT_LABEL, "--label", "P1", ...(values.local ? ["--label", "pendulum:local"] : [])); } finally { rmSync(dir, { recursive: true, force: true }); } const number = Number(url.split("/").pop()); await setType(number); filed.push({ number, title: o.title, url, filedAt: new Date().toISOString() }); - process.stderr.write(`filed #${number} ${o.title}\n`); + await gh("issue", "edit", String(number), "-R", repo, "--remove-label", DRAFT_LABEL); + process.stderr.write(`filed and activated #${number} ${o.title}\n`); } // The drill's own tick: dispatched through the API, which returns the run's id, recorded on each Objective it filed // (objective.mjs drillRecord) so the scorer reads that run as the drill's and not as operator input. A dispatch whose diff --git a/bench/lib/collect.mjs b/bench/lib/collect.mjs index 7431eef2..36d944b5 100644 --- a/bench/lib/collect.mjs +++ b/bench/lib/collect.mjs @@ -16,7 +16,8 @@ import { basename } from "node:path"; import { findFile } from "./gh.mjs"; import { ownRunArtifact } from "../../plugin/scripts/lib/github.mjs"; import { parseUsageText, sessionsOf } from "./cost.mjs"; -import { OBJECTIVE_LABEL } from "./objective.mjs"; +import { DRAFT_LABEL } from "../../plugin/scripts/lib/activation.mjs"; +import { labelTime, OBJECTIVE_LABEL } from "./objective.mjs"; import { bySelf, pendulumLogin } from "./phases.mjs"; const PER_PAGE = "per_page=100"; @@ -30,21 +31,31 @@ export const REVIEW_ARTIFACT = (issue) => `pendulum-usage-${issue}-review`; /** * The Objectives worth a row: issues with the label that closed at or after * `since` (ISO date), plus open ones carrying a Pendulum state label (Blocked, - * Question, In review, Running), so the misses that never merged are rows too. + * Question, In review, Running), so the misses that never merged are rows too. A draft that already ran is kept + * after its state labels have been cleared by stopping it. Closing a draft before activation does not create a row. * With `since`, also every issue whose label was removed at or after it (a * parked Objective, waiting on other work) and that Pendulum picked up then (a * state label applied at or after `since`): it ran and cost money, whatever its * labels are now, after the labelled ones. */ -export async function listObjectives(api, repoFull, { since, label = OBJECTIVE_LABEL, state = "all" } = {}) { +export async function listObjectives(api, repoFull, { since, label = OBJECTIVE_LABEL, state = "all", app = null } = {}) { const query = [`labels=${encodeURIComponent(label)}`, `state=${state}`, since ? `since=${encodeURIComponent(since)}` : null, "sort=updated", "direction=desc", PER_PAGE].filter(Boolean).join("&"); + const from = since ? Date.parse(since) : -Infinity; const issues = await api(`repos/${repoFull}/issues?${query}`, { paginate: true }); - const numbers = new Set( - issues - .filter((i) => !i.pull_request) - .filter((i) => (i.state === "closed" ? !since || Date.parse(i.closed_at ?? i.updated_at) >= Date.parse(since) : labelNames(i).some((n) => STATE_LABELS.includes(n)))) - .map((i) => i.number), - ); + const numbers = new Set(); + for (const issue of issues.filter((i) => !i.pull_request)) { + const closed = issue.state === "closed"; + if (closed && since && !(Date.parse(issue.closed_at ?? issue.updated_at) >= from)) continue; + const labels = labelNames(issue); + if (labels.some((name) => STATE_LABELS.includes(name)) || (closed && !labels.includes(DRAFT_LABEL))) { + numbers.add(issue.number); + } else if (labels.includes(DRAFT_LABEL)) { + const events = await api(`repos/${repoFull}/issues/${issue.number}/${closed ? "timeline" : "events"}?${PER_PAGE}`, { paginate: true }); + const worked = events.some((e) => e.event === "labeled" && STATE_LABELS.includes(e.label?.name) && (closed || Date.parse(e.created_at) >= from)); + const self = pendulumLogin(events, app); + if (worked || (closed && labelTime(issue, events, label, null, { mine: (c) => bySelf(c, self) }))) numbers.add(issue.number); + } + } if (since) for (const n of await parkedSince(api, repoFull, { since, label, skip: new Set(issues.map((i) => i.number)) })) numbers.add(n); return [...numbers]; } @@ -207,17 +218,18 @@ const JOB_ISSUE = /^(?:work|launch|merge tick) \((\d+)\)$|^review \(pendulum\/(\ /** * The runs of Pendulum's workflow a person started (`workflow_dispatch`) or re-ran (attempt 2 and up) while the - * Objective was live: from its first Objective or Running label to its merge (or its close, or now). Bots' runs are + * Objective was live: from its first activation to its merge (or its close, or now). Bots' runs are * left out here already. Each is `{id, event, attempt, created_at, run_started_at, by, issues}`, `issues` being the * Objectives its jobs name (`work (N)`, `launch (N)`, `merge tick (N)`, `review (pendulum/N)`), empty for a run tied to * none (a dispatcher tick). Throws when the runs cannot be read, or when GitHub's 1,000-run cap on a `created` filter - * may have cut the list. A re-run of a run created before the first label is not listed (the filter is on creation). + * may have cut the list. A re-run of a run created before activation is not listed (the filter is on creation). */ -export async function humanWorkflowRuns(api, repoFull, issueData, timeline, pulls, { workflow = PENDULUM_WORKFLOW } = {}) { - const starts = (timeline || []).filter((e) => e.event === "labeled" && (e.label?.name === OBJECTIVE_LABEL || e.label?.name === "pendulum:running")).map((e) => Date.parse(e.created_at)).filter(Number.isFinite); - if (!starts.length) return []; +export async function humanWorkflowRuns(api, repoFull, issueData, timeline, pulls, { workflow = PENDULUM_WORKFLOW, label = OBJECTIVE_LABEL, comments = [], app = null } = {}) { + const self = pendulumLogin(timeline, app); + const started = labelTime(issueData, timeline, label, null, { comments, mine: (c) => bySelf(c, self) }); + if (!started) return []; const iso = (t) => new Date(t).toISOString().replace(/\.\d{3}Z$/, "Z"); - const from = iso(Math.min(...starts)); + const from = iso(Date.parse(started)); const merged = (pulls || []).map((p) => Date.parse(p.merged_at)).filter(Number.isFinite); const endMs = merged.length ? Math.max(...merged) : Date.parse(issueData.closed_at) || null; const range = endMs ? `${from}..${iso(endMs)}` : `>=${from}`; @@ -250,7 +262,7 @@ export async function humanWorkflowRuns(api, repoFull, issueData, timeline, pull * (lib/gh.mjs's downloadArtifact bound to a token) or is null offline. * `usage` is a list of records read from --usage when given. */ -export async function collectObjective(api, repoFull, issue, { download = null, usage = null, jobs: wantJobs = true, graphql = null, app = null, workflow = PENDULUM_WORKFLOW } = {}) { +export async function collectObjective(api, repoFull, issue, { download = null, usage = null, jobs: wantJobs = true, graphql = null, app = null, workflow = PENDULUM_WORKFLOW, label = OBJECTIVE_LABEL } = {}) { const base = `repos/${repoFull}`; const issueData = await api(`${base}/issues/${issue}`); const [issueTimeline, issueComments, pullsOpen, pullsClosed] = await Promise.all([ @@ -326,7 +338,7 @@ export async function collectObjective(api, repoFull, issue, { download = null, } let workflowRuns = null; try { - workflowRuns = await humanWorkflowRuns(api, repoFull, issueData, issueTimeline, pulls, { workflow }); + workflowRuns = await humanWorkflowRuns(api, repoFull, issueData, issueTimeline, pulls, { workflow, label, comments: issueComments, app }); } catch { workflowRuns = null; // not readable with this token (actions: read): the row says so } diff --git a/bench/lib/objective.mjs b/bench/lib/objective.mjs index ebcd1f59..89fa8423 100644 --- a/bench/lib/objective.mjs +++ b/bench/lib/objective.mjs @@ -3,8 +3,8 @@ // "Job one and how 0.6 is measured"). Pure: takes the collected facts // (lib/collect.mjs online, a fixture offline) and returns the row. // -// walkAway binary. The clock starts at the first `pendulum:objective` -// label. Any human push, comment, review, edit, draft toggle or +// walkAway binary. The clock starts at the first activation, when Draft comes off or an old Objective label is +// applied outside Draft. Any human push, comment, review, edit, draft toggle or // merge on the branch or the issue after it breaks it; a Blocked // card (the pendulum:blocked label or the blocked marker comment) // is a miss. A Question answered by a human is a miss too. @@ -22,13 +22,14 @@ // ownerStep a posted workflow hand-over a person applies after the merge: // its minutes from --owner-minutes, apart from the operator's. // cost lib/cost.mjs (the plugin's cost-join.mjs), with unit and basis per harness. -// wall filed (label) to merged; runner minutes from the job log. -import { dispatchLatency, pendulumLogin, phaseMinutes, setupSeconds, stageLastWrite } from "./phases.mjs"; +// wall activation to merged; runner minutes from the job log. +import { bySelf, dispatchLatency, pendulumLogin, phaseMinutes, setupSeconds, stageLastWrite } from "./phases.mjs"; import { ACCOUNT, accountUse, costOf, decisionSpendRecords, stageHarnessOf, stageOf, stageSpendRecords, withLines } from "./cost.mjs"; import { BLOCK_CAUSES, blockCauseOf, rebaseTally, spendText } from "../../plugin/scripts/lib/logic.mjs"; import { billingText, unknownText } from "../../plugin/scripts/lib/usage.mjs"; import { HANDOVER_LABEL, carriesHandover, handoverMarker, handoverOf } from "../../plugin/scripts/lib/handover.mjs"; -import { clockRenamed, labelTime } from "../../plugin/scripts/lib/finish-card.mjs"; +import { activationEvents, DRAFT_LABEL, latestDraftEvent } from "../../plugin/scripts/lib/activation.mjs"; +import { clockRenamed, clockStart } from "../../plugin/scripts/lib/finish-card.mjs"; export const ROW_VERSION = 1; @@ -37,7 +38,6 @@ export { accountUse, stageHarnessOf, withLines }; const BRANCH = (issue) => `pendulum/${issue}`; export const RUNNING_LABEL = "pendulum:running"; export const OBJECTIVE_LABEL = "pendulum:objective"; -const DRAFT_LABEL = "pendulum:draft"; const BLOCKED_LABEL = "pendulum:blocked"; /** * The stall threshold's default, in minutes: a merged Objective idle longer than this after Pendulum's last action @@ -82,12 +82,8 @@ function commitActor(commit) { return { login: name || email || "unknown", type: "User", unlinked: true }; } -/** - * The clock: the first `labeled pendulum:objective` event, or null; a draft's start for a draft. With `clockAfter`, the - * first such event at or after that date: an issue that an earlier Pendulum already ran under the same label starts its - * clock there. The finish card starts its clock the same way, so the rule lives with it (plugin finish-card.mjs). - */ -export { labelTime }; +/** The finish card and scorer share an Objective's first activation. */ +export { labelTime } from "../../plugin/scripts/lib/finish-card.mjs"; /** * Minutes of the wall clock spent waiting rather than working: from the clock to Pendulum's first @@ -95,7 +91,8 @@ export { labelTime }; * next Running label (a human's turn). Null without a merge; the basis says what counted. */ export function waitingMinutes(timeline, since, mergedAt) { - if (!since || !mergedAt) return { minutes: null, basis: "not merged" }; + if (!mergedAt) return { minutes: null, basis: "not merged" }; + if (!since) return { minutes: null, basis: "clock start not recorded" }; const labels = (timeline || []).filter((e) => e.event === "labeled" && e.label?.name && ms(e.created_at) >= ms(since)).sort((a, b) => ms(a.created_at) - ms(b.created_at)); let total = 0; const parts = []; @@ -134,7 +131,7 @@ export function decisionsOf(actions) { * - labels: only the pendulum state labels the local loop sets (running, in-review, blocked, question, review) are * Pendulum's, and removing pendulum:restart once it restarted the Objective. Any other label, applying * pendulum:restart and re-applying pendulum:objective among them, is a person's. Removing pendulum:blocked is - * Pendulum's only after a re-applied Objective label (the recovery it answers); without one it is a person's + * Pendulum's only after a new activation (the recovery it answers); without one it is a person's * manual un-block. * - comments: Pendulum's comments all carry a `` marker. One without a marker is a person's, even * inside a run (an answer to a Question typed while the stage was running). @@ -180,10 +177,12 @@ export function localPendulumActions(collected, { label = OBJECTIVE_LABEL } = {} const handoverLabel = (at) => handoverBodies.length > 0 || inRun(at); const dropped = handoverBodies.some((b) => handoverOf(b.slice(mark.length)) === null); const relabeled = (at) => labels.some((e) => e.label?.name === HANDOVER_LABEL && (e.actor?.login ?? e.actor?.name) === login && ms(e.created_at) > ms(at) && handoverLabel(e.created_at)); - // Pendulum lifts its own Blocked only on recovery: the Objective label re-applied after the latest block. + // Pendulum lifts its own Blocked only on a new activation after the latest block. + const timeline = collected.issueTimeline || []; + const starts = activationEvents(timeline, label, { assumeObjective: true }); const recovered = (at) => { const block = labels.filter((e) => e.label?.name === BLOCKED_LABEL && ms(e.created_at) <= ms(at)).at(-1); - return !!block && labels.some((e) => e.label?.name === label && ms(e.created_at) >= ms(block.created_at) && ms(e.created_at) <= ms(at)); + return !!block && starts.some((e) => ms(e.created_at) <= ms(at) && (ms(e.created_at) > ms(block.created_at) || (ms(e.created_at) === ms(block.created_at) && timeline.indexOf(e) > timeline.indexOf(block)))); }; return (at, actor, kind, id = null) => { if (tidied(at, actor, kind, id)) return true; @@ -325,31 +324,36 @@ function triageReruns(collected, login) { } /** The human actions after `since` on the issue and its PRs, oldest first: each {at, where, kind, by, detail}. */ -export function humanActions(collected, since, { bots = new Set(), label = OBJECTIVE_LABEL } = {}) { +export function humanActions(collected, since, { bots = new Set(), label = OBJECTIVE_LABEL, start = clockStart(collected.issueTimeline, label, since) } = {}) { const out = []; - const after = (at) => Number.isFinite(ms(at)) && ms(at) > ms(since); + const sinceMs = ms(since); + const timeline = collected.issueTimeline || []; + const startIndex = ms(start?.created_at) === sinceMs ? timeline.indexOf(start) : -1; const pendulumLocal = localPendulumActions(collected, { label }); - const push = (at, where, kind, actor, detail = "", id = null) => { - if (after(at) && isHuman(actor, bots) && !pendulumLocal(at, actor, kind, id)) out.push({ at, where, kind, by: actor.login ?? actor.name ?? "unknown", detail }); + const push = (at, where, kind, actor, detail = "", id = null, timelineIndex = -1) => { + const atMs = ms(at); + const after = atMs > sinceMs || (atMs === sinceMs && startIndex >= 0 && timelineIndex > startIndex); + if (after && isHuman(actor, bots) && !pendulumLocal(at, actor, kind, id)) out.push({ at, where, kind, by: actor.login ?? actor.name ?? "unknown", detail }); }; const issue = `#${collected.issue.number}`; + const author = collected.issue.user?.login; + const filedAt = ms(collected.issue.created_at); const branch = branchPulls(collected); const mergedTimes = branch.filter((pr) => pr.merged_at).map((pr) => ms(pr.merged_at)); - for (const e of collected.issueTimeline || []) { + for (const [i, e] of timeline.entries()) { if (mergeConsequence(e.event, e.created_at, mergedTimes)) continue; // Passive events (mentioned, subscribed, cross-referenced from elsewhere) and bookkeeping (issue type, // milestone, pin, project card) are not input to the Objective's work. if (PASSIVE_EVENTS.has(e.event)) continue; - if (e.event === "labeled" && e.label?.name === label && e.created_at === since) continue; // the clock itself - if (e.event === "unlabeled" && e.label?.name === DRAFT_LABEL && e.created_at === since) continue; // a draft's start: the clock - // Labels the issue's author applies while filing it (a priority, the type's labels) are part of filing, not input. - if (e.event === "labeled" && (e.actor?.login ?? null) === (collected.issue.user?.login ?? undefined) && ms(e.created_at) - ms(collected.issue.created_at) <= 60_000) continue; + // Legacy direct starts could bundle filing metadata with the Objective label. A Draft hold is always input. + if (start?.label?.name === label && e.event === "labeled" && e.label?.name !== DRAFT_LABEL && author && e.actor?.login === author && + ms(e.created_at) >= filedAt && ms(e.created_at) - filedAt <= 60_000) continue; if (e.event === "commented") { if (/`; for (const e of collected.issueTimeline || []) if (e.event === "labeled" && e.label?.name === QUESTION_LABEL && ms(e.created_at) >= ms(since)) return { at: e.created_at, source: "label" }; - for (const pr of collected.pulls || []) if (/\bQUESTION\b/.test(pr.body || "")) return { at: pr.created_at, source: `PR #${pr.number} body` }; - for (const c of collected.issueComments || []) if ((c.body || "").includes(plan) && /\bQUESTION\b/.test(c.body || "")) return { at: c.created_at, source: "plan comment" }; + for (const pr of collected.pulls || []) if (ms(pr.created_at) >= ms(since) && /\bQUESTION\b/.test(pr.body || "")) return { at: pr.created_at, source: `PR #${pr.number} body` }; + for (const c of collected.issueComments || []) if (ms(c.created_at) >= ms(since) && (c.body || "").includes(plan) && /\bQUESTION\b/.test(c.body || "")) return { at: c.created_at, source: "plan comment" }; return null; } @@ -810,9 +814,20 @@ export function scoreObjective(collected, opts = {}) { // read: the owner's read of the merged diff ("ok", "defect" or "unread"), given with --read, kept across --append. const issue = collected.issue; const missing = []; - let since = labelTime(issue, collected.issueTimeline, label, clockAfter); - let sinceBasis = clockAfter ? `first "${label}" label at or after ${clockAfter}` : `first "${label}" label`; - if (!since) { + const self = pendulumLogin(collected.issueTimeline, app); + const start = clockStart(collected.issueTimeline, label, clockAfter, { issue: issue.number, comments: collected.issueComments, mine: (c) => bySelf(c, self) }); + const labels = issue.labels?.map((l) => (typeof l === "string" ? l : l?.name)); + const draft = labels?.includes(DRAFT_LABEL); + const noStart = !start && (draft || latestDraftEvent(collected.issueTimeline) !== null); + let since = start?.created_at ?? null; + let sinceBasis = start?.label.name === DRAFT_LABEL ? `first removal of "${DRAFT_LABEL}"` + : start?.label.name === RUNNING_LABEL ? `first "${RUNNING_LABEL}" label` + : `first "${label}" label`; + if (clockAfter) sinceBasis += ` at or after ${clockAfter}`; + if (noStart) { + sinceBasis = "Draft has no recorded activation"; + missing.push("Draft activation event"); + } else if (!since) { since = clockAfter && ms(issue.created_at) < ms(clockAfter) ? clockAfter : issue.created_at; sinceBasis = clockAfter && since === clockAfter ? `--clock-after (no "${label}" label event at or after it)` : `issue created (no "${label}" label event found)`; missing.push("label event"); @@ -829,17 +844,16 @@ export function scoreObjective(collected, opts = {}) { const open = pulls.find((pr) => !pr.merged_at && pr.state === "open") ?? null; const blocked = blockedAt(collected, since); const question = questionAt(collected, since); - let actions = humanActions(collected, since, { bots, label }); + let actions = humanActions(collected, since, { bots, label, start }); const waiting = waitingMinutes(collected.issueTimeline, since, merged?.merged_at ?? null); const exit = merged ? "merged" : blocked ? "blocked" : question ? "question" : open ? (open.draft ? "draft" : "in review") : pulls.length ? "closed unmerged" : "no PR"; - // Parked: open, its label removed after Pendulum took it (it waits on other work). Its exit still says where it + // Parked: open, made a draft or its identity label removed after activation. Its exit still says where it // stopped; it is never a walk-away (not merged) and the streak counts it only once it ended (lib/streak.mjs endedAt). - const parked = issue.state === "open" && !missing.includes("label event") && Array.isArray(issue.labels) && !issue.labels.some((l) => (typeof l === "string" ? l : l?.name) === label); + const parked = issue.state === "open" && !!start && !!labels && (draft || !labels.includes(label)); const pendulumLocal = localPendulumActions(collected); // Every body edit after the clock by a person, oldest first: never Pendulum's own login (its App's finish block on the // merged PR's body, plugin finish-card.mjs), nor, in local mode, what localPendulumActions says is Pendulum's. - const self = pendulumLogin(collected.issueTimeline, app); const bodyEdit = [...(collected.bodyEdits || [])].sort((a, b) => ms(a.at) - ms(b.at)).find((e) => ms(e.at) > ms(since) && isHuman(e.by, bots) && !(self && e.by?.login === self) && !pendulumLocal(e.at, e.by, "body edit")) ?? null; if (bodyEdit) actions.unshift({ at: bodyEdit.at, where: bodyEdit.where, kind: "body edit", by: bodyEdit.by.login, detail: "" }); if (collected.bodyEdits === null) missing.push("body edits (GraphQL unavailable)"); // undefined: not attempted (a fixture or a snapshot) @@ -877,7 +891,7 @@ export function scoreObjective(collected, opts = {}) { const stall = idle?.stalled ? { minutes: idle.minutes, from: idle.from, until: idle.until, thresholdMinutes: idle.thresholdMinutes } : null; const stallReason = stall ? `stalled ${stall.minutes} min after Pendulum's last action (${stall.from} to ${stall.until}; threshold ${stall.thresholdMinutes} min)` : null; const walkAway = { - value: Boolean(merged) && !blocked && actions.length === 0 && !stall, + value: Boolean(merged) && !blocked && !noStart && actions.length === 0 && !stall, // The rule this row scored a workflow hand-over by (HANDOVER_SCORING). handover, since, @@ -895,10 +909,11 @@ export function scoreObjective(collected, opts = {}) { }; walkAway.blocks = blockStops(collected, since, { bots }); walkAway.bucket = walkAwayBucket({ value: walkAway.value, blocks: walkAway.blocks, question, actions: split, stall, unseen }); + const walkAwayReason = `merged with no human action after ${start?.label.name === DRAFT_LABEL ? "Draft removal" : "the label"}${ownerNote}`; walkAway.reason = walkAway.value - ? `merged with no human action after the label${ownerNote}` - : !merged - ? `not merged (${exit}${blocked?.reason ? `: ${blocked.reason}` : ""})` + ? walkAwayReason + : !merged || noStart + ? (merged ? "merged with no recorded activation" : `not merged (${exit}${blocked?.reason ? `: ${blocked.reason}` : ""})`) : blocked ? `Blocked at ${blocked.at}${blocked.reason ? `: ${blocked.reason}` : ""}` : actions.length @@ -907,8 +922,8 @@ export function scoreObjective(collected, opts = {}) { // Walk-away counting only what Pendulum asked for: a merge with no Blocked and no human action answering a request. // Unprompted actions (an owner's note, scope added after the label) are left out of this one, never out of `value`. walkAway.askedOnly = { - value: Boolean(merged) && !blocked && asked.length === 0 && !stall, - reason: !merged + value: Boolean(merged) && !blocked && !noStart && asked.length === 0 && !stall, + reason: !merged || noStart ? walkAway.reason : blocked ? walkAway.reason @@ -918,8 +933,13 @@ export function scoreObjective(collected, opts = {}) { ? `first asked-for action: ${asked[0].kind} on ${asked[0].where} by ${asked[0].by} at ${asked[0].at}, answering a ${asked[0].asked}` : unprompted.length ? `merged; ${unprompted.length} unprompted human action(s), none asked for` - : `merged with no human action after the label${ownerNote}`, + : walkAwayReason, }; + if (merged && noStart) { + walkAway.value = null; + walkAway.bucket = "unknown"; + walkAway.askedOnly.value = null; + } // Labelled before the rename (`renamed`): a walk-away with every input source read, and an asked-only yes, are not // known; anything else stays as read, noted (a walk-away with an input source unread still breaks the streak). if (renamed) { @@ -957,7 +977,7 @@ export function scoreObjective(collected, opts = {}) { let operator; if (typeof given === "number" && Number.isFinite(given)) operator = { minutes: given, basis: "--minutes (stopwatch)" }; - else if (renamed) operator = { minutes: "unknown", basis: `${RENAMED_WHY}; give --minutes = from a stopwatch` }; + else if (renamed || noStart) operator = { minutes: "unknown", basis: `${renamed ? RENAMED_WHY : sinceBasis}; give --minutes = from a stopwatch` }; else if (walkAway.value) operator = { minutes: 0, basis: ownerStep ? "clean merge; the owner step's minutes are apart (ownerStep)" : "clean merge" }; else if (merged && !blocked && !actions.length) operator = { minutes: 0, basis: "no human action (stalled)" }; else operator = { minutes: "unknown", basis: actions.some((a) => a.kind === "workflow hand-over") ? "a workflow hand-over is a person's step: give --minutes = from a stopwatch" : "give --minutes = from a stopwatch" }; @@ -1014,7 +1034,7 @@ export function scoreObjective(collected, opts = {}) { runnerMinutes: runner.minutes, runnerBasis: runner.basis, wallMinutes: wall, - wallBasis: !merged ? "not merged" : renamed ? "unknown: labelled before the rename to Pendulum" : `${sinceBasis} to merged`, + wallBasis: !merged ? "not merged" : renamed ? "unknown: labelled before the rename to Pendulum" : noStart ? sinceBasis : `${sinceBasis} to merged`, waitingMinutes: renamed ? null : waiting.minutes, waitingBasis: renamed ? RENAMED_WHY : waiting.basis, workingMinutes: wall === null || waiting.minutes === null ? null : Math.max(0, Math.round((wall - waiting.minutes) * 10) / 10), @@ -1085,7 +1105,7 @@ export const ownerCell = (r) => (r.ownerStep ? `${fmtMin(r.ownerStep.minutes)} ( /** The summary under the table: walk-away both ways, the interventions split and the owner steps, over every row. */ export function summaryLine(rows) { - // A row labelled before the rename (bucket `unknown`) is in no walk-away count. + // A row with an unknown clock is in no walk-away count. const unknown = rows.filter((r) => r.walkAway.bucket === "unknown"); const n = rows.length - unknown.length; const merged = rows.filter((r) => r.exit === "merged" && r.walkAway.bucket !== "unknown").length; @@ -1098,6 +1118,8 @@ export function summaryLine(rows) { const owners = rows.filter((r) => r.ownerStep); const inputs = rows.filter((r) => !r.ownerStep && (r.walkAway.interventions?.requests || []).some((q) => q.kind === "workflow hand-over")); const handovers = `${owners.length ? ` Owner steps (a workflow hand-over, scored as normal work, its minutes apart): ${owners.map((r) => `#${r.issue} ${ownerCell(r)}`).join(", ")}.` : ""}${inputs.length ? ` Workflow hand-overs scored as input: ${inputs.map((r) => `#${r.issue}`).join(", ")}.` : ""}`; - const notKnown = unknown.length ? ` Not known (labelled before the rename to Pendulum), in no count: ${unknown.map((r) => `#${r.issue}`).join(", ")}.` : ""; + const unknownNote = (affected, why) => affected.length ? ` Not known (${why}), in no count: ${affected.map((r) => `#${r.issue}`).join(", ")}.` : ""; + const notKnown = unknownNote(unknown.filter((r) => r.walkAway.clockRenamed), "labelled before the rename to Pendulum") + + unknownNote(unknown.filter((r) => !r.walkAway.clockRenamed), "Draft activation was not recorded"); return `Walk-away: ${strict} of ${n} Objective(s) (${merged} merged) with no human input; ${askedOnly} of ${n} counting only input Pendulum asked for. Interventions: ${sum("asked")} asked for (Question, Blocked notice, review request), ${sum("unprompted")} unprompted.${stalls}${handovers}${notKnown}`; } diff --git a/bench/lib/streak.mjs b/bench/lib/streak.mjs index e680243d..df17eaa5 100644 --- a/bench/lib/streak.mjs +++ b/bench/lib/streak.mjs @@ -11,8 +11,8 @@ // One still running, in review or waiting on a Question has not finished: it is listed as in flight, neither. // An External one (walkAway.bucket: its only stops were external Blocks, lib/objective.mjs walkAwayBucket) is listed // in the sequence as skipped: it neither extends nor breaks, and does not count as finished. A P1 escape found in its -// merge makes it a break. A walk-away merge labelled before the rename to Pendulum (bucket `unknown`: whether it was one -// is not known) is skipped the same way, unless a P1 escape makes it a break; a miss or an External result seen after +// merge makes it a break. A merge with an unknown activation clock (bucket `unknown`) is skipped the same way, +// unless a P1 escape makes it a break; a miss or an External result seen after // its later label is scored as any other. // A workflow hand-over scored as an owner step (lib/objective.mjs HANDOVER_SCORING, the default) leaves the merge a // walk-away: it extends the streak, and its entry says it carries an owner step (`ownerStep`). Scored as input, it breaks. @@ -36,7 +36,7 @@ export function endedAt(row) { /** One finished row's verdict for the streak: `{ok, why}`; an External row's is `{ok: null, external: true, why}`, skipped. */ export function verdict(row) { const escapes = (row.quality?.escapes || []).filter(isP1); - // A walk-away merge labelled before the rename (bucket `unknown`): skipped, unless a P1 escape or an input source not + // A merge with an unknown activation clock: skipped, unless a P1 escape or an input source not // read breaks it. const unread = row.walkAway?.unseen === undefined ? ["input sources not recorded"] : row.walkAway.unseen; if (row.walkAway?.bucket === "unknown" && unread.length) return { ok: false, why: `input not readable (${unread.join(", ")}): walk-away unproven` }; diff --git a/bench/score.mjs b/bench/score.mjs index 0da72088..c492880b 100644 --- a/bench/score.mjs +++ b/bench/score.mjs @@ -39,7 +39,7 @@ * comments alone are read (default: the App that * applied pendulum:running to the issue) * --label NAME the Objective label (default pendulum:objective) - * --clock-after DATE start each clock at the first label event at or + * --clock-after DATE start each clock at the first activation event at or * after DATE (an issue an earlier Pendulum ran under * the same label keeps its old events; this floors them) * --check CMD validation command(s) for the grade-auto line @@ -221,14 +221,14 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) if (!sinceAt) usage(`--since ${sinceTag}: no such tag in ${pendulumRepo}`); } for (const repo of repos) { - const numbers = issues.length ? issues : await listObjectives(api, repo, { since: sinceAt, label }); + const numbers = issues.length ? issues : await listObjectives(api, repo, { since: sinceAt, label, app: values.app ?? null }); if (!numbers.length) { process.stderr.write(`no ${label} issue in ${repo} closed${values.since ? ` since ${values.since}` : ""}, Blocked, Question, In review, Running or parked\n`); if (!pooled) process.exit(65); } byRepo[repo] = []; for (const issue of numbers) { - const collected = snapshot?.collected?.[issue] ?? (await collectObjective(api, repo, issue, { download, usage: usageFor(issue, numbers.length) ?? (usageDir ? [] : null), jobs: !values["no-jobs"], graphql, app: values.app ?? null, ...(values.workflow ? { workflow: values.workflow } : {}) })); + const collected = snapshot?.collected?.[issue] ?? (await collectObjective(api, repo, issue, { download, usage: usageFor(issue, numbers.length) ?? (usageDir ? [] : null), jobs: !values["no-jobs"], graphql, app: values.app ?? null, label, ...(values.workflow ? { workflow: values.workflow } : {}) })); // --usage decides on a replay too: an issue without its own directory has none, whatever the snapshot stored. if (usageDir && snapshot) collected.usage = usageFor(issue, numbers.length) ?? []; collected.harness = collected.usage.find((r) => r.harness)?.harness ?? collected.harness ?? null; diff --git a/bench/skills.json b/bench/skills.json index 6355f5da..48aebf56 100644 --- a/bench/skills.json +++ b/bench/skills.json @@ -31,14 +31,14 @@ } }, "pendulum-file": { - "sha256": "adb4a849f35b2ae82dc64b948f28307ffc9cea9636b39ecba61d83e045baeab7", + "sha256": "fc2686110ede525203de594c0e9a2a146ffc03ae97390326978bd5e4430045d6", "lines": 46, - "words": 698, + "words": 617, "files": { "reference.md": { - "sha256": "0fe89a54b00271a37ca5a88370cc0cb780e54982e4f12cc0c07845ccd020726a", - "lines": 65, - "words": 1315 + "sha256": "5888e13c3416e62ada9a2392e4214c6609447f5433d7961483e0bc7db678d31a", + "lines": 67, + "words": 1297 } } }, @@ -113,9 +113,9 @@ } }, "pendulum-restart": { - "sha256": "024f7c1771559a35af1cb4cb27ae20d8ce68f458b9ca91fcfd99355aaec7696f", + "sha256": "ff194bf1bfb423176d4b140aca09ff852751f99f837d25367cbe750b30ba3942", "lines": 31, - "words": 503 + "words": 466 }, "pendulum-review-here": { "sha256": "e2f838041dc541e9ddae7dcfdcf30336c173075ed898ba3629e024ac8896d526", @@ -147,14 +147,14 @@ } }, "pendulum-run": { - "sha256": "f3c10fe6bbd65f65eed377bddee3cc892b8a13f464e1521eb48e75c7e83cf409", - "lines": 51, - "words": 697, + "sha256": "baa4bd811618416dd11be7882856482525944ffb09c15a3f0ff822cd4f7cceb4", + "lines": 53, + "words": 668, "files": { "reference.md": { - "sha256": "f2108baad9ce2f7c8e223fab1af4648c562cd10a3b16f7cdda430ba44a9921bf", - "lines": 17, - "words": 266 + "sha256": "9ac608b8543691e5fef32a94d95b9b1438de704ddfb4f6633e91b54c21085f3e", + "lines": 23, + "words": 379 } } }, @@ -171,9 +171,9 @@ } }, "pendulum-serve": { - "sha256": "0e096df2718d379c7b7aa42cf7362caa06568235d1684136e539d4dc58c50c1d", - "lines": 31, - "words": 611, + "sha256": "8bc302bb5e8c7640043bb5382998e65f8023b7b372f3d10309563fe42c8c7853", + "lines": 37, + "words": 675, "files": { "reference.md": { "sha256": "77f3d282e3f1b96115b51261f19fbe1aa287c172711fed774f5d38862d322d7e", @@ -200,21 +200,21 @@ } }, "pendulum-status": { - "sha256": "8e3ebb1612da3f034b6948b6799771371ad7c6590781bf51ccda21118beefd1b", + "sha256": "394333b54d1b472dca28682f9cf8a0acd8154bf97f3a6048d45ac76957f974d9", "lines": 40, - "words": 692, + "words": 630, "files": { "reference.md": { - "sha256": "03d8ddd00f6a2ffe7ba4b7beef905c8546f32676031adb506c7f831610673d70", - "lines": 46, - "words": 879 + "sha256": "b0da1fe6f1bb255963fe1373d6a2ba81155003433879f7e60969eb407cf35ea2", + "lines": 55, + "words": 967 } } }, "pendulum-stop": { - "sha256": "d29e0447f3d681856d11a70b36eb461d2c5e71e516e89195fe5838b702702417", + "sha256": "6d2377a327e8a697efc404836f6483cbd0b738a0ad9bfde83de0753710ff43f5", "lines": 30, - "words": 457 + "words": 404 } } } diff --git a/bench/test/score.test.mjs b/bench/test/score.test.mjs index 6bc36ac1..3d039931 100644 --- a/bench/test/score.test.mjs +++ b/bench/test/score.test.mjs @@ -7,12 +7,13 @@ import { cpSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, stat import { tmpdir } from "node:os"; import { join } from "node:path"; import { test } from "node:test"; -import { collectObjective, snapshotApi, usageDirFor, usageFromDir } from "../lib/collect.mjs"; +import { collectObjective, humanWorkflowRuns, snapshotApi, usageDirFor, usageFromDir } from "../lib/collect.mjs"; import { costOf, loadPrices, parseUsageText, priceTokens } from "../lib/cost.mjs"; import { RENAMED_WHY, humanActions, localPendulumActions, markdownTable, scoreObjective, summaryLine } from "../lib/objective.mjs"; import { blocked, cleanMerge, humanPush, localMerge, OPERATOR, REPO, snapshotOf, withHandover } from "./fixtures/github.mjs"; import { CODEX_NO_TOKENS } from "../../plugin/scripts/lib/usage.mjs"; import { PREVIOUS_NAME } from "../../plugin/scripts/lib/local.mjs"; +import { refusedMarker } from "../../plugin/scripts/lib/stop.mjs"; import { newForms } from "../../plugin/test/fixtures/progress-new-form.mjs"; const BENCH = join(import.meta.dirname, ".."); @@ -38,6 +39,101 @@ test("clean merge: walk-away yes, operator 0, Claude dollars from total_cost_usd assert.equal(row.mergedBy, "acme-pendulum[bot]"); }); +test("Draft removal starts the walk-away clock and workflow lookback; preparation and activation are not interventions", async () => { + const c = cleanMerge(42, usage("claude")); + const [filed, ...working] = c.issueTimeline; + const draft = { ...filed, label: { name: "pendulum:draft" } }; + const startAt = "2031-03-02T01:02:00Z"; + const start = { ...draft, created_at: startAt, event: "unlabeled" }; + const preparation = { user: OPERATOR, created_at: "2031-03-02T01:01:00Z", body: "Prep the acceptance wording." }; + c.issueTimeline = [filed, draft, start, ...working]; + c.issueComments.unshift(preparation); + let query; + await humanWorkflowRuns(async (path) => { + query = decodeURIComponent(path); + return []; + }, REPO, c.issue, c.issueTimeline, c.pulls); + assert.match(query, /created=2031-03-02T01:02:00Z\.\./); + const row = scoreObjective(c, { prices }); + assert.deepEqual([row.walkAway.since, row.walkAway.sinceBasis, row.walkAway.humanActions, row.walkAway.value, row.wallMinutes], [startAt, 'first removal of "pendulum:draft"', 0, true, 148]); + + const held = { ...c, issue: { ...c.issue, state: "open", closed_at: null, labels: [filed.label, draft.label] }, issueTimeline: [draft, filed], pulls: [] }; + const waiting = scoreObjective(held, { prices }); + assert.deepEqual([waiting.walkAway.since, waiting.wallMinutes, waiting.parked], [null, null, false]); + + const resumeAt = "2031-03-02T02:00:00Z"; + c.issueTimeline.push({ ...draft, created_at: "2031-03-02T01:45:00Z" }, { ...start, created_at: resumeAt }); + const resumed = scoreObjective(c, { prices }); + assert.deepEqual([resumed.walkAway.since, resumed.walkAway.humanActions, resumed.walkAway.value], [startAt, 2, false]); +}); + +test("issue-timeline order counts human actions after the exact activation in the same second", () => { + const c = cleanMerge(42, usage("claude")); + const [filed, ...working] = c.issueTimeline; + c.issue.created_at = filed.created_at; + const draft = { ...filed, label: { name: "pendulum:draft" } }; + const at = "2031-03-02T01:00:20Z"; + const held = { ...draft, created_at: at }; + const start = { ...held, event: "unlabeled" }; + const comment = (body) => ({ actor: OPERATOR, created_at: at, event: "commented", body }); + const ownerLabel = { ...filed, actor: c.issue.user, label: { name: "priority" }, created_at: "2031-03-02T01:00:40Z" }; + c.issueTimeline = [filed, draft, comment("Preparatory note"), start, comment("Change after start"), { ...held }, { ...start }, ownerLabel, ...working]; + const actions = humanActions(c, at); + assert.deepEqual(actions.map(({ kind, detail }) => [kind, detail]), [ + ["comment", "Change after start"], + ["labeled pendulum:draft", ""], + ["unlabeled pendulum:draft", ""], + ["labeled priority", ""], + ]); + assert.equal(scoreObjective(c, { prices }).walkAway.humanActions, 4); +}); + +test("legacy direct starts keep bundled filing metadata out of walk-away and count a later Draft hold", () => { + const c = cleanMerge(42, usage("claude")); + const [filed, ...working] = c.issueTimeline; + c.issue.created_at = filed.created_at; + const ownerLabel = (name, created_at = filed.created_at) => ({ ...filed, label: { name }, actor: c.issue.user, created_at }); + c.issueTimeline = [filed, ownerLabel("priority"), ownerLabel("pendulum:local"), ...working]; + assert.equal(scoreObjective(c, { prices }).walkAway.value, true); + + c.issueTimeline.splice(3, 0, ownerLabel("pendulum:draft", "2031-03-02T01:00:40Z")); + const row = scoreObjective(c, { prices }); + assert.deepEqual([row.walkAway.value, row.walkAway.humanActions, row.walkAway.firstHumanAction.kind], [false, 1, "labeled pendulum:draft"]); +}); + +test("only a Pendulum-owned refusal excludes the exact Draft removal from clock and workflow lookback", async () => { + const c = cleanMerge(42, usage("claude")); + const [filed, ...working] = c.issueTimeline; + const draft = { ...filed, label: { name: "pendulum:draft" } }; + const at = "2031-03-02T01:02:00Z"; + const rejected = { ...draft, id: 901, created_at: at, event: "unlabeled" }; + const chosen = { ...rejected, id: 902 }; + const bot = working.find((e) => e.label?.name === "pendulum:running").actor; + const refusal = (id, user) => ({ user, created_at: at, body: refusedMarker(c.issue.number, { id, at }) }); + c.issueTimeline = [filed, draft, rejected, { ...draft, created_at: at }, chosen, ...working]; + c.issueComments.unshift(refusal(901, bot), refusal(902, OPERATOR)); + const row = scoreObjective(c, { prices }); + assert.deepEqual([row.walkAway.since, row.walkAway.humanActions, row.walkAway.value], [at, 0, true]); + c.issueTimeline.splice(4, 1, { ...chosen, created_at: "2031-03-02T01:03:00Z" }); + let query; + await humanWorkflowRuns(async (path) => { + query = decodeURIComponent(path); + return []; + }, REPO, c.issue, c.issueTimeline, c.pulls, { comments: c.issueComments }); + assert.match(query, /created=2031-03-02T01:03:00Z\.\./); +}); + +test("missing Draft removal leaves the merged wall clock and walk-away unknown", () => { + const c = cleanMerge(42, usage("claude")); + const [filed, ...working] = c.issueTimeline; + c.issueTimeline = [filed, { ...filed, label: { name: "pendulum:draft" } }, ...working]; + const row = scoreObjective(c, { prices }); + assert.deepEqual([row.walkAway.since, row.walkAway.value, row.walkAway.askedOnly.value, row.walkAway.bucket, row.wallMinutes], [null, null, null, "unknown", null]); + assert.ok(row.missing.includes("Draft activation event")); + assert.equal(row.operator.minutes, "unknown"); + assert.match(summaryLine([row]), /Not known \(Draft activation was not recorded\), in no count: #42\./); +}); + test("human push: a maintainer's commit on the branch after the label breaks walk-away and names itself", () => { const row = scoreObjective(humanPush(43, usage("claude")), { prices, now: NOW }); assert.equal(row.exit, "merged"); diff --git a/bench/test/streak.test.mjs b/bench/test/streak.test.mjs index 35fcb004..017726ed 100644 --- a/bench/test/streak.test.mjs +++ b/bench/test/streak.test.mjs @@ -8,7 +8,7 @@ import { mkdtempSync, writeFileSync, readFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { test } from "node:test"; -import { humanWorkflowRuns } from "../lib/collect.mjs"; +import { humanWorkflowRuns, listObjectives } from "../lib/collect.mjs"; import { loadPrices } from "../lib/cost.mjs"; import { humanActions, p1Escapes, scoreObjective } from "../lib/objective.mjs"; import { pooledStreak, pooledTable, streaks, streakTable, verdict } from "../lib/streak.mjs"; @@ -254,6 +254,30 @@ test("a parked Objective is a row: stopped when Blocked, in flight when its Ques assert.equal(score(blocked(72)).parked, false); }); +test("draft Objectives are collected only after activation when closed or after a stage when open", async () => { + const filed = "2031-03-01T00:00:00Z"; + const activated = "2031-03-02T00:00:00Z"; + const identity = "pendulum:objective"; + const draft = "pendulum:draft"; + const display = (number, state) => ({ number, state, closed_at: state === "closed" ? "2031-03-05T00:00:00Z" : null, labels: [identity, draft] }); + const label = (event, name, created_at) => ({ event, created_at, label: { name } }); + const filing = [label("labeled", identity, filed), label("labeled", draft, filed)]; + const afterStart = [...filing, label("unlabeled", draft, activated), label("labeled", "pendulum:running", activated), label("labeled", draft, "2031-03-04T00:00:00Z")]; + const rows = [display(80, "closed"), display(81, "open"), display(82, "closed"), display(83, "open"), display(84, "closed"), display(85, "closed")]; + const app = "pendulum-app[bot]"; + const refused = [...filing, { ...label("unlabeled", draft, activated), id: 123 }, + { event: "commented", body: "", user: { login: app } }, + label("labeled", draft, "2031-03-04T00:00:00Z")]; + const api = async (path) => { + if (path.includes("/issues?")) return rows; + const n = Number(/\/issues\/(\d+)\/(?:events|timeline)\?/.exec(path)?.[1]); + assert.ok(n >= 80 && n <= 85, path); + if (n === 85) return [...filing, label("labeled", "pendulum:running", activated)]; + return n === 84 ? refused : n < 82 ? filing : afterStart; + }; + assert.deepEqual(await listObjectives(api, REPO, { since: filed, app }), [82, 83, 85]); +}); + test("pooledStreak: two repositories' rows in the order they ended, any harness; any miss resets it", () => { const A = "acme/widgets"; const B = "acme/gadgets"; diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 4ee34e5e..f4261e83 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -35,7 +35,7 @@ What each credential can do: - **The job token:** `contents: read`, `issues: write`, `actions: read` (usage artifacts and the CI workflow's triggers), and on the jobs that tick the dispatcher `actions: write` (work and review also use it to rerun flaky CI jobs); it never writes code. Your repository's default workflow token must be read-only, which doctor requires and setup's `default-token` step sets (below). - **The harness:** it holds no GitHub write access: on Actions it runs as its own uid with a read-only token (the runner needs passwordless sudo, as GitHub's hosted runners have); Pendulum makes every write. - **Secrets:** they are scrubbed from every non-harness child and masked in the uploaded event log. -- **Cost:** `max_usd` caps each job ($25 by default). `daily_usd` ($100 by default) gates new stages: once the UTC day's spend reaches it, the dispatcher starts and relaunches no stage until the next day, while running stages, review stages and answer passes go on, so a day can end above it. Every stage, on every route, writes its spend so far into its progress comment, and that line is what the day, the finish card and `max_objective_usd` count; a usage artifact is read for its dollars only for a stage whose comment has no spend line, and the finish card reads one for its model alone for a stage whose harness line names none (Copilot at its default model). `max_objective_usd` (unset by default: no cap) caps one Objective across all its stages and parts: every work and review stage checks it before any pass, and once the Objective's known spend reaches it, the stage starts nothing and the Objective Blocks naming the cap and the total (cause `max-objective-usd`); raise or unset it, then re-apply `pendulum:objective`. It counts, since the Objective's last `pendulum:restart` or reopening (a restart starts the count over), the known dollars of every stage of Pendulum's on the issue (its spend line, else its own workflow run's usage artifact), the cloud sandbox's vendor cost, and the decision calls made outside any stage that Pendulum's comments on the issue record (a line in a comment written since then, or dated after that day). A stage on another route Pendulum cannot match to itself, and every run of unknown cost, count nothing. A stage's own spend counts once its spend line is written, so the stage that crosses the cap finishes. `max_concurrent` is 3 and `timeout_minutes` 240 unless set; setup's `--preset first-run` sets `max_usd` 5, `max_concurrent` 1 and `auto_merge` false for a first run; Claude (`--max-budget-usd`) and Copilot (`--max-ai-credits`) enforce the per-job cap inside the run; Codex is checked after each run. A job's passes get `max_usd` less its drift reserve (10% of `max_usd`, at least $0.30, at most `max_usd`), which only the drift advisory spends (`decision_route` below). The caps count only spend a harness, Copilot, the AI Gateway or the sandbox vendor reported (or API-reported tokens at the published rate). A run whose cost was not reported (killed or crashed before it reported, a zeroed Claude result, a resumed Claude Code session before 2.1.277, a Codex model with no price row, a Copilot run whose AI credits were not reported, a relayed gateway call or a gateway decision call the gateway never priced) is shown as unknown, "plus N runs of unknown cost", in the progress comment, the exit line, `result.json`, the day's total and the scorecard; it is not counted against `max_usd`, `daily_usd` or `max_objective_usd` and the job goes on, so a cap can be exceeded by unreported spend. Only the provider's own budget or limit bounds that. Each figure also says how it is billed (`billing` and `usdByBilling` in `result.json` and the spend line), decided on a positive sign only, from the environment the harness gets and what the harness reports: +- **Cost:** `max_usd` caps each job ($25 by default). `daily_usd` ($100 by default) gates new stages: once the UTC day's spend reaches it, the dispatcher starts and relaunches no stage until the next day, while running stages, review stages and answer passes go on, so a day can end above it. Every stage, on every route, writes its spend so far into its progress comment, and that line is what the day, the finish card and `max_objective_usd` count; a usage artifact is read for its dollars only for a stage whose comment has no spend line, and the finish card reads one for its model alone for a stage whose harness line names none (Copilot at its default model). `max_objective_usd` (unset by default: no cap) caps one Objective across all its stages and parts: every work and review stage checks it before any pass, and once the Objective's known spend reaches it, the stage starts nothing and the Objective Blocks naming the cap and the total (cause `max-objective-usd`); raise or unset it, then resume through Draft as described in [An Objective's lifecycle](USAGE.md#an-objectives-lifecycle). It counts, since the Objective's last `pendulum:restart` or reopening (a restart starts the count over), the known dollars of every stage of Pendulum's on the issue (its spend line, else its own workflow run's usage artifact), the cloud sandbox's vendor cost, and the decision calls made outside any stage that Pendulum's comments on the issue record (a line in a comment written since then, or dated after that day). A stage on another route Pendulum cannot match to itself, and every run of unknown cost, count nothing. A stage's own spend counts once its spend line is written, so the stage that crosses the cap finishes. `max_concurrent` is 3 and `timeout_minutes` 240 unless set; setup's `--preset first-run` sets `max_usd` 5, `max_concurrent` 1 and `auto_merge` false for a first run; Claude (`--max-budget-usd`) and Copilot (`--max-ai-credits`) enforce the per-job cap inside the run; Codex is checked after each run. A job's passes get `max_usd` less its drift reserve (10% of `max_usd`, at least $0.30, at most `max_usd`), which only the drift advisory spends (`decision_route` below). The caps count only spend a harness, Copilot, the AI Gateway or the sandbox vendor reported (or API-reported tokens at the published rate). A run whose cost was not reported (killed or crashed before it reported, a zeroed Claude result, a resumed Claude Code session before 2.1.277, a Codex model with no price row, a Copilot run whose AI credits were not reported, a relayed gateway call or a gateway decision call the gateway never priced) is shown as unknown, "plus N runs of unknown cost", in the progress comment, the exit line, `result.json`, the day's total and the scorecard; it is not counted against `max_usd`, `daily_usd` or `max_objective_usd` and the job goes on, so a cap can be exceeded by unreported spend. Only the provider's own budget or limit bounds that. Each figure also says how it is billed (`billing` and `usdByBilling` in `result.json` and the spend line), decided on a positive sign only, from the environment the harness gets and what the harness reports: - **Billed per use, shown bare:** an Anthropic API key (`ANTHROPIC_API_KEY`, an `apiKeyHelper`, a Console login), workload identity federation, a bearer token to a gateway or proxy (`ANTHROPIC_AUTH_TOKEN`), Bedrock or Vertex (`CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`), a Codex API key or API auth mode, the AI Gateway key (its decision calls, in a stage or outside one), and a relayed worker key's calls. - **"API-equivalent at list prices, on the subscription":** Claude Code's `total_cost_usd` on `credential: plan` (`CLAUDE_CODE_OAUTH_TOKEN`) or on a local login whose Claude Code reports a subscription's rate-limit windows, and Codex tokens priced from the API table on a ChatGPT auth mode (or a local login whose rollout carries a ChatGPT plan's rate limits). - **"Copilot AI credits, billed to the seat":** Copilot's credits at `copilot_credit_usd`. @@ -265,7 +265,7 @@ The accounts are rendered into the workflow, so adding, removing or reordering o 1. Read the release notes between your tag and the new one. 2. Re-render the workflow with that release's setup: in your repository's clone, `node /plugin/scripts/setup.mjs --repo OWNER/NAME --apply workflow --action clockgrove/pendulum@vX.Y.Z --yes`. It keeps your settings, moves the pin and brings the template's jobs to that release. Re-render on every upgrade: the template belongs to its release, and an older file misses jobs the new Action expects (doctor names some, such as `merge ticks`). -3. Commit the file on the default branch, then run doctor. A running `pendulum serve` started from a release takes a later pin at its next stage boundary, without a restart (LOCAL.md, Settings and repins while `serve` runs); to go back to an older release, start `serve` from it yourself. Until then the file lacks the newer jobs' events: a file from before the lifecycle labels, for one, ticks the dispatcher on a removed `pendulum:objective`, an applied `pendulum:restart` or a changed `pendulum:draft` only on its ten-minute cron. +3. Commit the file on the default branch, then run doctor. A running `pendulum serve` started from a release takes a later pin at its next stage boundary, without a restart (LOCAL.md, Settings and repins while `serve` runs); to go back to an older release, start `serve` from it yourself. Until then the file lacks the newer jobs' events: a file from before the lifecycle labels, for one, waits for its ten-minute cron to see a change to `pendulum:draft`, an applied `pendulum:restart` or a legacy Objective-label removal. 4. If you accepted setup's offer to commit Pendulum's skills into the repository, copy them again from the new release: committed copies never update, and they override the plugin's. 5. Update the plugin on each machine whose sessions or `pendulum serve` work this repository, then start a new session: Claude Code `claude plugin marketplace update clockgrove && claude plugin update pendulum@clockgrove`, Codex `codex plugin marketplace upgrade clockgrove && codex plugin add pendulum@clockgrove`, Copilot `copilot plugin update pendulum@clockgrove`. Doctor and `pendulum serve` warn while the installed plugin is older than the pin. diff --git a/docs/LOCAL.md b/docs/LOCAL.md index 49f3c264..1a3ae353 100644 --- a/docs/LOCAL.md +++ b/docs/LOCAL.md @@ -177,20 +177,20 @@ The next `serve` on the same machine resumes them first, before reviews and new - Running work starts a fresh work pass in the Objective's clone, on the branch as GitHub has it (a killed pass's session and unpushed commits are not carried over). Other machines and the Action leave a paused Objective alone. -The dispatcher Blocks one only after the claim pause away (`claim_pause_hours`, a day by default), and re-applying its label brings it back. +The dispatcher Blocks one only after the claim pause away (`claim_pause_hours`, a day by default). Once the cause is fixed, resume it through Draft after the previous stage has stopped. [An Objective's lifecycle](USAGE.md#an-objectives-lifecycle) ### Stopping one Objective -Removing its `pendulum:objective` label (applying `pendulum:draft`, or closing its issue) is not a pause. +Apply `pendulum:draft` to stop an Objective and keep its `pendulum:objective` identity. Closing the issue also stops it. This is separate from pausing a process by stopping the local loop. Its stage here reads the issue once a minute, ends its harness's process group, records its spend line and exits with `exit: stopped`. The loop drops its claim, does not resume it, and starts no review of its PR, which the stage leaves a draft. A validation or setup command running at the stop is not in the harness's group: it runs to its end after the stage exits, and the stage starts no command, push or PR change after the stop. -`serve`'s next tick tidies a stopped one no stage holds (USAGE.md, An Objective's lifecycle). +`serve`'s next tick tidies a stopped one no stage holds. Once the stage has stopped and released its claim, remove `pendulum:draft` to return the Objective to the queue. [An Objective's lifecycle](USAGE.md#an-objectives-lifecycle) ### Drafts -An issue with `pendulum:draft` is never run here: `serve` neither picks, resumes nor reviews it, and `pendulum run`, `pendulum issue` and `pendulum deliver` refuse it before any claim, naming how to start it. +File a draft with both `pendulum:objective` and `pendulum:draft`. While Draft is on the issue, `serve` skips it for new work, resumes and reviews. `pendulum run`, `pendulum issue` and `pendulum deliver` refuse it before any claim. Removing `pendulum:draft` lets the next tick consider it on its configured route. ### Restarting one Objective @@ -203,20 +203,22 @@ It forgets this loop's failed starts and lapses of it, and the next work stage p An Objective whose stage ends on this machine with a Question or a Block waits for you. No `serve` tick takes it again while its stage runs, or after it ends on a GitHub read that does not show the stop yet. It starts again only after a trusted answer, the same as on the Action: -- **Re-applying its label.** +- **Removing `pendulum:draft` after the cause is resolved.** Add Draft first if it is absent. Leave `pendulum:objective` in place. - **A comment answering a Question asked on the issue** (one with no PR, or the plan-time Question; its notice on the issue says to answer there). The next `serve` tick reads the comments made since the Question by people who can push, Pendulum's own marked comments not among them though they post as your login. It runs the worker again with the answer, once the answer check reads the comments as a decision on the Question (PLAN.md, Exit: question). - **Marking the PR ready, for a Question its draft PR asks** (its notice says to mark the PR ready). The next `serve` tick reviews that PR, and the review applies the answer; with none since the Question, the PR goes back to a Question. -A label re-applied since the Question by someone who can push (USAGE.md, who applied a label counts) wins over a ready mark beside it: the next tick runs the worker, its `pendulum:question` label taken off, and starts no review of that PR. +A trusted Draft removal since the Question takes precedence over marking the PR ready. The next tick clears `pendulum:question` and starts the worker without starting a review of that PR. [Who applied a label counts](USAGE.md#choose-the-harness-and-models) Marking a plan-time Question's PR ready starts a review that can merge the part done so far, as its notice warns: answer that one on the issue. If the stop never reached GitHub (a fresh read of the issue shows it Queued), it runs again, as on the Action, and the tick line names every Objective it holds. ### Waiting on the queue +When a session supervises the queue, it checks the issue's readiness and follows the existing dispatcher. The assigned worker handles source discovery and implementation. A loop pick or Running label can appear before work begins. Use a recorded stage start or current claim to confirm it. + `pendulum wait` is for an agent that supervises the queue: started in the background, it exits when something needs a look. It reads GitHub, not this machine, so it tells every route's Objectives (the Action's, a cloud sandbox's, any machine's `serve`), with or without a `serve` here. It needs no sandbox, harness or App, and reads with the local token, else your `gh` login. @@ -365,7 +367,7 @@ It resumes a paused Objective once the host it could not reach answers a probe, **Twelve hours.** An Objective paused on one outage for twelve hours or more is Blocked instead, with the External cause `outage`, naming the host and since when. - That happens on `serve`'s first tick that GitHub answers, whether or not that host answers yet (a model provider that stays unreachable while GitHub works ends here too); the notice says whether the host answers again or is still unreachable. - Re-apply its label to run it again. + Resume it through Draft once the cause is resolved. - An outage that begins within fifteen minutes of `serve` resuming the Objective counts as the same one. Pauses on GitHub's spent rate limit one after another, with no other end between, count as one however long the runs between them last. Either holds only while nothing was done between them: a stage whose provider served a harness pass (its `result.json`'s `servedPasses`; a decision call Pendulum made through the harness is none) before it paused made progress, so its pause counts from its own start. @@ -799,7 +801,7 @@ No sandbox can read it; it must be a regular file of yours, with one link, that The scorecard also gives each account's stages, dollars and usage-limit pauses for the Objective. No path, credential or token reaches GitHub or a log. - **Checked at every stage start, every account:** a bad one stops `serve` from starting, and Blocks a stage (cause `setup`), naming only the account; the loop's log says why, without a path. - Fix the file, then re-apply `pendulum:objective`. + Fix the file, then resume the Objective through Draft. Pendulum never creates an account folder. These are bad: - an invalid or repeated name, or another harness's name; @@ -934,7 +936,7 @@ For one Objective's stages alone they also reach the hosts its approved `pendulu `*.` over a public suffix or a name with one below, such as `*.github.io` or `*.amazonaws.com`, is refused, but a name that resolves to a loopback or link-local address is not. Doctor's `objective hosts` row lists them. - A worker that stops because a sandbox denied a host it needs names the host in its exit record (`deniedHosts`). - The Blocked comment names it with both fixes: a `pendulum:host:` label for this Objective, or the host in `PENDULUM_LOCAL_DOMAINS` for every Objective (`serve` reads it when it starts), then re-apply `pendulum:objective`. + The Blocked comment names it with both fixes: a `pendulum:host:` label for this Objective, or the host in `PENDULUM_LOCAL_DOMAINS` for every Objective (`serve` reads it when it starts), then resume through Draft. Allowing it stays your decision. ### Git LFS media is uploaded by Pendulum, not the sandbox diff --git a/docs/PLAN.md b/docs/PLAN.md index 39e7a3be..c5eed811 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -1,6 +1,6 @@ # Pendulum: design and contracts -Pendulum is a GitHub Action, a harness plugin and a bench, sharing one set of skills and a short task card. An adopter adds one workflow file, a GitHub App and a model credential, and labels an issue `pendulum:objective`; a worker builds it, a reviewer comments on it, and Pendulum merges it through the adopter's own required checks and merge queue. The human reads the Project board's Blocked column and, when they choose, the merged diffs. This page is the design as it is now; git holds its history. +Pendulum is a GitHub Action, a harness plugin and a bench, sharing one set of skills and a short task card. An adopter adds one workflow file, a GitHub App and a model credential, and files an issue with `pendulum:objective` and `pendulum:draft`. Removing Draft makes it eligible to run. A worker builds it, a reviewer comments on it, and Pendulum merges it through the adopter's own required checks and merge queue. The human reads the Project board's Blocked column and, when they choose, the merged diffs. This page is the design as it is now; git holds its history. ## Design rules @@ -46,7 +46,7 @@ Job one: file an Objective, walk away, and come back to correct, merged work at | Measure | Job-one part | Taken from | | --- | --- | --- | -| Walk-away: merged with zero human input after the label | Operator walks away | Three buckets. Walk-away: merged with no human push, comment or edit on the branch or issue after the label. External: every stop was a Block outside Pendulum and outside the work (Pendulum's `max_usd` cap, the AI Gateway's budget or credits, a provider's quota, plan limit or billing: the model provider, GitHub's Git LFS storage, GitHub's API rate limit or the sandbox vendor's plan; a provider or GitHub outage Pendulum handled by its rules), and the only human input answered those Blocks. Miss: anything else, a Blocked card of any other cause included. Each Block records its cause as a code (bench/README.md, Block causes), so the bucket is decided on structure. | +| Walk-away: merged with zero human input after activation | Operator walks away | Three buckets. Walk-away: merged with no human push, comment or edit on the branch or issue after activation. External: every stop was a Block outside Pendulum and outside the work (Pendulum's `max_usd` cap, the AI Gateway's budget or credits, a provider's quota, plan limit or billing: the model provider, GitHub's Git LFS storage, GitHub's API rate limit or the sandbox vendor's plan; a provider or GitHub outage Pendulum handled by its rules), and the only human input answered those Blocks. Miss: anything else, a Blocked card of any other cause included. Each Block records its cause as a code (bench/README.md, Block causes), so the bucket is decided on structure. | | Solution quality | Correct work | The bench's blind pairwise judge where there is a comparison; the owner's read of the merged diff when they choose to read it; escapes found after merge count against it. | | Operator minutes | Operator walks away | Minutes spent on Blocked cards and on re-filing, from a stopwatch; zero on a clean merge. | | Dollars per merged Objective | Reasonable cost | Per harness: Claude's headless output carries total\_cost\_usd and per-model usage with sub-agents included; Codex's JSONL carries the thread's running token counts (a resumed pass counts only its own share), priced from a table, with each sub-agent thread's own counts read from its rollout and priced at its model; Copilot bills GitHub AI Credits and its usage file reports them per run, so its column is those credits at GitHub's published $0.01 each (configurable), with the premium requests beside them. Runner minutes beside it. Wall time reported, never alone. | @@ -185,13 +185,13 @@ One worker, three routes: a GitHub runner (the default), the developer's own mac ## How an Objective flows -1. **File.** A writer opens an issue stating the Objective (goal, acceptance entries under an Acceptance heading, sources, context, recorded decisions) and a maintainer applies `pendulum:objective`. The Project card is Queued. An issue with `pendulum:draft` is a draft: no route runs it, its Objective label on or not, until a person takes the draft label off and applies `pendulum:objective`. `lib/stop.mjs` decides it: the dispatcher, the launcher, the worker, the review job, the merge pass and the local loop's resumes and reviews read `stopCause`; `pendulum run`, `pendulum issue` and `pendulum deliver` refuse on `isDraft`. A work stage plans by the later of the label's last application and the draft label's last removal (`objective-trust.mjs` `startedAt`), so a draft edited after an earlier plan is planned again once started. Blocked-by relations on the issue are the only dependency graph; an issue closed by any route counts as done. +1. **File.** A writer opens an issue stating the Objective (goal, acceptance entries under an Acceptance heading, sources, context, recorded decisions) and a maintainer files it with `pendulum:objective` and `pendulum:draft`. The issue keeps its Objective identity for its entire lifecycle. The Project card is Queued. Every route skips drafts. The maintainer removes `pendulum:draft` to activate the Objective. `lib/stop.mjs` decides it: the dispatcher, the launcher, the worker, the review job, the merge pass and the local loop's resumes and reviews read `stopCause`; `pendulum run`, `pendulum issue` and `pendulum deliver` refuse on `isDraft`. A work stage plans by the latest trusted activation (`objective-trust.mjs` `startedAt`), so a draft edited after an earlier plan is planned again once started. Older Objective-label events remain readable. Blocked-by relations on the issue are the only dependency graph; an issue closed by any route counts as done. 2. **Dispatch.** The dispatcher, ticked by events (any issue closing among them, since it may block an Objective) and by Pendulum's own jobs, with GitHub's `*/10` cron as the backstop, picks ready Objectives by priority label and starts work up to `max_concurrent`, stopping at `daily_usd`. A pick whose known files (its open PR's changed files, its plan comment's `Files:` lines) overlap an active sibling's starts all the same, saying so on its issue: it has work of its own to write, and waiting would hold that whole stage where starting costs at most one rebase. What waits is the hand-off: a head no review has seen that conflicts with the head of a sibling ahead of it (In review, or through its own wait and rebasing, or waiting since earlier), by a trial merge of the two heads against the default branch (git merge-tree in a scratch mirror), when Pendulum merges, gets its review label only once no such sibling is ahead (for 6 hours at most from the Objective's first wait), after its rebase if it conflicts by then. Waiting PRs go one at a time in the order they began waiting, so each rebases once and two such PRs are never reviewed or queued at once (`lib/overlap.mjs`; `docs/USAGE.md` "Siblings that touch the same files"). The card moves to Running. 3. **Work.** The worker checks out the default branch, runs `setup`, installs the versions the lockfile pins (online, with no credential in its environment; npm, pnpm and yarn skip install scripts), renders the task card and starts the harness with the issue text verbatim. The harness writes its plan, implements, rebases, validates and commits, and leaves its plan, PR text and exit record as files. Pendulum posts the plan, pushes `pendulum/` and opens the one PR. With required checks configured (`ci_checks`) and a work pass that ended well, Pendulum does not wait for the checks on that head: once the push is done (on the local route, once its validation commands are green on the machine), it marks the PR ready with a hand-off marker (``) instead of the validated one and applies the review label, so the review starts while the head's first required-check run is still going. A send-back's rebase, and a pass whose harness ended in an error (green checks are what outweigh it), wait for the checks in the work stage. With cross-OS CI on (`cross_os_workflow`, `cross_os_checks`; INSTALL.md, Cross-OS CI), the work stage then dispatches the repository's named CI workflow on the branch (in a cloud sandbox, through its launcher job, which dispatches only that workflow on the stage's own branch and head and hands the run's id back) and waits, within `cross_os_wait_minutes`, for the macOS and Windows legs it lists, on every route; a red leg goes to the fix pass as any validation red does, a head a fix pass made gets the other validation again first, and only once the legs are green does the hand-off or the validated marker follow (`lib/cross-os.mjs`). The card moves to In review. 4. **Review.** The reviewer posts findings as PR review comments. On a head handed off with its checks running, the review stage waits for the checks beside the reviewer (Review and merge, below). The worker gets the comments once, with any red the checks showed, and addresses or rebuts each in a reply file; Pendulum pushes its commits, posts the replies, and validation runs again. -5. **Merge.** Pendulum merges the reviewed head once its required checks are green, through the merge queue where there is one. A red integrated run whose failure is in the PR's own change gets one fix pass, as a red PR check does, before any Block: one per failure class and two in all per re-entry, so the same failure red again after its fix pass Blocks. A red integrated run that is a flake, GitHub's side or the default branch's, or that cannot be read or (with triage off) named as the PR's, and any other drop, goes back to the queue once; a second is Blocked (Review and merge, below). So a repository may run a light check on the PR and its full suite only in the merge queue. A PR that conflicts because other PRs merged (when its review reaches the merge, or in the merge queue) is sent back to the worker for a rebase each time the default branch has moved since its last rebase: a new base is progress. When Pendulum merges, the PRs that conflict go back in the release order (priority, then number): one whose head conflicts, by a trial merge, with that of a sibling ahead of it in that order that will merge first (In review, or rebasing after its review) waits for that merge, since a rebase now would be undone by it, for 6 hours at most counted with any hand-off wait before it, with a record on the PR and a note on the issue (`lib/overlap.mjs` sendBackOrder). Each send-back is its own work stage, with its own `max_usd`; its notice on the PR says which rebase of the 24-hour bound it is, and its progress comment carries a `` line (its known dollars, 0 for a clean rebase, its runs of unknown cost as its spend line carries them, and whether it was a conflict pass) beside the Objective's rebase total so far. It Blocks, as the work's, only when rebasing cannot progress, or at the bound. The worker records each rebase of Pendulum's that conflicts on the PR (the head it started from, the base and the files), and before anything of its conflict pass is pushed it checks the checkout: a rebase, merge or cherry-pick left in progress, a head that does not contain that base, or a change of the branch missing from it Blocks naming the files and each path whose change is missing (with the branch's commits that changed it, and why), with nothing pushed. That is decided on the branch's net change, its merge base with the base to its head, merges included, never on commit ids, authors or subjects, so a rebased or squashed branch, or one with a commit of the worker's joining it to the default branch, goes out when it keeps the work. The net change is replayed onto the base (`git merge-tree`, with git's rename detection, so a file the default branch renamed is checked under its new name) and merged into the head: every path that replay conflicts on and every path that merge would still change is checked, and nothing else is the branch's. Such a path is kept when the head has exactly the branch's version of it, content and file mode. The file mode is decided on its own: a mode the branch's change sets and the head lacks is named, whatever the content. A binary or Git LFS file, a submodule or symlink, and a file git cannot merge the branch's change into (one the head moved or removed, or kept with edits where the branch deletes it) are decided exactly, never by the model. A change of the branch with no hunk is decided exactly too: two different blobs (git reads one as binary, the base included) are named, a file the branch only puts under a name (one side of a rename) or adds empty is named when the head has no file there, an empty file it deletes is named when the head keeps it, and a name the branch's change does not have is no loss. Any other text file goes to the decision model (with a key, `triage_model`; else the stage's harness: Red-check triage below), four files at a time. The branch's change is, for a file the replay conflicted on, its side from their base; for a file where merging the branch's change into the head conflicts, its side of that merge; for any other, what that merge would still change there. Its hunks, whatever the size of the whole diff, go in one question with the file as the head has it: whole, or, over 32 KiB, for each hunk the 60 lines either side of where its lines are in the head (from the first line, for a file the base did not have), reaching past every line its new side has. A question holds at most 64 KiB: more goes in groups of hunks packed in order up to that, each group with the file or its hunks' lines, the groups asked at once (four questions at a time across the check). The question is whether every hunk's effect is still in the file, as written or adapted to the default branch's code, other changes and additions allowed; each part is delimited, with the path, as untrusted data the model is told not to follow. `kept` at the confidence floor or more (Red-check triage, below) keeps the file. Anything else, for a question of several hunks, asks each of its hunks alone, sent with the file or its lines again, in order, and names the file with the first hunk not kept; no further group starts. When every hunk alone is kept, the question's hunks are kept after an unsure answer for them together (`kept` or `lost` under the floor, or none), and the file still named after a `lost` at the floor or more. A hunk whose own question (the hunk with the file, or with its lines around it) is over 64 KiB is not judged: the file is named with each such hunk, and its other hunks are not asked. The Block names the fix for a generated file: declare it. A path the default branch's `.gitattributes` gives the `pendulum-generated` attribute, in a repository with a `regenerate` command, is never judged: the conflict pass takes the default branch's version, the command writes the file again, and Pendulum's regeneration check runs the command before each validation, in any stage, of a head whose change touches a declared path, green only when it exits 0, writes again each such file (removed first), changes nothing outside the declared paths and leaves each declared path as committed (INSTALL.md, Generated files). A path past the first 40 or the check's 3 minutes names the file. On the local route, a conflict pass the check stops is kept on the branch `pendulum/-conflict-pass` of the Objective's clone, `.pendulum//repo` (the last one only: a later push of the branch removes it, and so does a later Block with nothing to keep, which says so), and the Block gives its full sha and how to deliver it: check that it keeps the Objective's change and touches no secret or protected path, since Pendulum's push checks did not run on it, then `git push --force-with-lease origin pendulum/-conflict-pass:pendulum/` in that clone and re-apply the Objective's label; the stages after it validate and review that head like any other. A file the branch's commits changed and then undid, which the head changes anyway, is no loss: when the branch goes out, a line on the progress comment says so for the review. With no decider (`decision_route` off, or `gateway` with no key), a path not exactly the branch's falls back to matching the branch's commits in the head by author, author time and subject (a commit git dropped because the base already has its change is no loss), as does a stage with no decider whose git is older than 2.40; with a key, such a git Blocks naming its version. The check asks whether the branch's change is still there; whether the joined code still works (a call to something the default branch renamed, a semantic clash that keeps every line) is for validation, CI and the reviewer. As a fallback, the dispatcher Blocks, naming the files, a PR that still conflicts while the default branch is the base the last pushed rebase was made onto. The bound is 5 rebases in 24 hours by default (`rebase_limit`), so two Objectives cannot chase each other forever; a batch of five parallel Objectives has at most four siblings merging ahead of one. Only Pendulum's own markers and records count, and a tick that cannot read them, or the Objective label's time, holds the PR until the next. A PR that only fell behind and whose update-branch GitHub fails for now waits for the next tick; one GitHub refuses goes to the worker under these rules. A PR the merge queue takes out for a conflict with a PR ahead of it counts as no drop: Pendulum puts it back once no PR in the queue conflicts with it, by a trial merge of the two heads against the default branch (git merge-tree in a scratch mirror), and at once when a trial merge cannot be computed (the queue then answers). Each time it goes back in, Pendulum records on the issue the queue's state then (the default branch's head and every entry's head); taken out for a conflict again, it goes back in only once that state has changed, so a conflict pairwise trials cannot see (one with the queue's merge group) never loops. This is the same on every route and harness: nothing is enqueued for a conflicting PR, it stays delivered, and the send-back takes it (`pendulum run --wait` does the send-back itself). The card moves to Done and the issue closes. -6. **Blocked.** The PR becomes a draft, the card moves to Blocked, and one comment states the reason (validation failed twice, reviewer findings unaddressed, dollar or time cap reached, worker died twice, rebasing makes no progress or reached its bound). The queue does not wait. A human fixes it by pushing to the branch or editing the issue and re-applying the label; a local Block on hosts the sandbox denied names them and its own fix (Exit: blocked, below). -7. **Stopped.** A person removes `pendulum:objective`, applies `pendulum:draft` or closes the issue. Nothing lists a stopped Objective for a start (the dispatcher, the local loop's resumes and reviews, the sandbox launcher, the review job). A running stage reads its issue once a minute and on the stop ends every harness pass (`lib/stop.mjs`), records the spend so far and exits with `exit: stopped`; from the stop on it starts no pass, command, push or PR change, and it writes its usage and spend line before any other GitHub call (at two minutes it writes what it knows at once and exits). A pass ended before it reported dollars, or still running, is a run of unknown cost, as on the spend line. A cloud sandbox stage that its launcher process ends instead (its wall clock) records the stage as a run of unknown cost too (`stage.mjs` `killedUsage`), never `max_usd` or another bound, so `daily_usd` names it without counting it. A stop racing the stage's own exit (one being applied, or its merge) ends nothing, and the merge pass reads the issue before any merge, so a stopped Objective never merges; its PR leaves the merge queue and becomes a draft without `pendulum:review`, and its state label and card go back to Queued. The dispatcher does the same for a stopped Objective In review, and for a Running one ten minutes after the stop. Re-applying the label continues it, as after a Block. +5. **Merge.** Pendulum merges the reviewed head once its required checks are green, through the merge queue where there is one. A red integrated run whose failure is in the PR's own change gets one fix pass, as a red PR check does, before any Block: one per failure class and two in all per re-entry, so the same failure red again after its fix pass Blocks. A red integrated run that is a flake, GitHub's side or the default branch's, or that cannot be read or (with triage off) named as the PR's, and any other drop, goes back to the queue once; a second is Blocked (Review and merge, below). So a repository may run a light check on the PR and its full suite only in the merge queue. A PR that conflicts because other PRs merged (when its review reaches the merge, or in the merge queue) is sent back to the worker for a rebase each time the default branch has moved since its last rebase: a new base is progress. When Pendulum merges, the PRs that conflict go back in the release order (priority, then number): one whose head conflicts, by a trial merge, with that of a sibling ahead of it in that order that will merge first (In review, or rebasing after its review) waits for that merge, since a rebase now would be undone by it, for 6 hours at most counted with any hand-off wait before it, with a record on the PR and a note on the issue (`lib/overlap.mjs` sendBackOrder). Each send-back is its own work stage, with its own `max_usd`; its notice on the PR says which rebase of the 24-hour bound it is, and its progress comment carries a `` line (its known dollars, 0 for a clean rebase, its runs of unknown cost as its spend line carries them, and whether it was a conflict pass) beside the Objective's rebase total so far. It Blocks, as the work's, only when rebasing cannot progress, or at the bound. The worker records each rebase of Pendulum's that conflicts on the PR (the head it started from, the base and the files), and before anything of its conflict pass is pushed it checks the checkout: a rebase, merge or cherry-pick left in progress, a head that does not contain that base, or a change of the branch missing from it Blocks naming the files and each path whose change is missing (with the branch's commits that changed it, and why), with nothing pushed. That is decided on the branch's net change, its merge base with the base to its head, merges included, never on commit ids, authors or subjects, so a rebased or squashed branch, or one with a commit of the worker's joining it to the default branch, goes out when it keeps the work. The net change is replayed onto the base (`git merge-tree`, with git's rename detection, so a file the default branch renamed is checked under its new name) and merged into the head: every path that replay conflicts on and every path that merge would still change is checked, and nothing else is the branch's. Such a path is kept when the head has exactly the branch's version of it, content and file mode. The file mode is decided on its own: a mode the branch's change sets and the head lacks is named, whatever the content. A binary or Git LFS file, a submodule or symlink, and a file git cannot merge the branch's change into (one the head moved or removed, or kept with edits where the branch deletes it) are decided exactly, never by the model. A change of the branch with no hunk is decided exactly too: two different blobs (git reads one as binary, the base included) are named, a file the branch only puts under a name (one side of a rename) or adds empty is named when the head has no file there, an empty file it deletes is named when the head keeps it, and a name the branch's change does not have is no loss. Any other text file goes to the decision model (with a key, `triage_model`; else the stage's harness: Red-check triage below), four files at a time. The branch's change is, for a file the replay conflicted on, its side from their base; for a file where merging the branch's change into the head conflicts, its side of that merge; for any other, what that merge would still change there. Its hunks, whatever the size of the whole diff, go in one question with the file as the head has it: whole, or, over 32 KiB, for each hunk the 60 lines either side of where its lines are in the head (from the first line, for a file the base did not have), reaching past every line its new side has. A question holds at most 64 KiB: more goes in groups of hunks packed in order up to that, each group with the file or its hunks' lines, the groups asked at once (four questions at a time across the check). The question is whether every hunk's effect is still in the file, as written or adapted to the default branch's code, other changes and additions allowed; each part is delimited, with the path, as untrusted data the model is told not to follow. `kept` at the confidence floor or more (Red-check triage, below) keeps the file. Anything else, for a question of several hunks, asks each of its hunks alone, sent with the file or its lines again, in order, and names the file with the first hunk not kept; no further group starts. When every hunk alone is kept, the question's hunks are kept after an unsure answer for them together (`kept` or `lost` under the floor, or none), and the file still named after a `lost` at the floor or more. A hunk whose own question (the hunk with the file, or with its lines around it) is over 64 KiB is not judged: the file is named with each such hunk, and its other hunks are not asked. The Block names the fix for a generated file: declare it. A path the default branch's `.gitattributes` gives the `pendulum-generated` attribute, in a repository with a `regenerate` command, is never judged: the conflict pass takes the default branch's version, the command writes the file again, and Pendulum's regeneration check runs the command before each validation, in any stage, of a head whose change touches a declared path, green only when it exits 0, writes again each such file (removed first), changes nothing outside the declared paths and leaves each declared path as committed (INSTALL.md, Generated files). A path past the first 40 or the check's 3 minutes names the file. On the local route, a conflict pass the check stops is kept on the branch `pendulum/-conflict-pass` of the Objective's clone, `.pendulum//repo` (the last one only: a later push of the branch removes it, and so does a later Block with nothing to keep, which says so), and the Block gives its full sha and how to deliver it: check that it keeps the Objective's change and touches no secret or protected path, since Pendulum's push checks did not run on it, then `git push --force-with-lease origin pendulum/-conflict-pass:pendulum/` in that clone and resume through Draft; the stages after it validate and review that head like any other. A file the branch's commits changed and then undid, which the head changes anyway, is no loss: when the branch goes out, a line on the progress comment says so for the review. With no decider (`decision_route` off, or `gateway` with no key), a path not exactly the branch's falls back to matching the branch's commits in the head by author, author time and subject (a commit git dropped because the base already has its change is no loss), as does a stage with no decider whose git is older than 2.40; with a key, such a git Blocks naming its version. The check asks whether the branch's change is still there; whether the joined code still works (a call to something the default branch renamed, a semantic clash that keeps every line) is for validation, CI and the reviewer. As a fallback, the dispatcher Blocks, naming the files, a PR that still conflicts while the default branch is the base the last pushed rebase was made onto. The bound is 5 rebases in 24 hours by default (`rebase_limit`), so two Objectives cannot chase each other forever; a batch of five parallel Objectives has at most four siblings merging ahead of one. Only Pendulum's own markers and records count, and a tick that cannot read them, or the Objective label's time, holds the PR until the next. A PR that only fell behind and whose update-branch GitHub fails for now waits for the next tick; one GitHub refuses goes to the worker under these rules. A PR the merge queue takes out for a conflict with a PR ahead of it counts as no drop: Pendulum puts it back once no PR in the queue conflicts with it, by a trial merge of the two heads against the default branch (git merge-tree in a scratch mirror), and at once when a trial merge cannot be computed (the queue then answers). Each time it goes back in, Pendulum records on the issue the queue's state then (the default branch's head and every entry's head); taken out for a conflict again, it goes back in only once that state has changed, so a conflict pairwise trials cannot see (one with the queue's merge group) never loops. This is the same on every route and harness: nothing is enqueued for a conflicting PR, it stays delivered, and the send-back takes it (`pendulum run --wait` does the send-back itself). The card moves to Done and the issue closes. +6. **Blocked.** The PR becomes a draft, the card moves to Blocked, and one comment states the reason (validation failed twice, reviewer findings unaddressed, dollar or time cap reached, worker died twice, rebasing makes no progress or reached its bound). The queue does not wait. A human fixes it by pushing to the branch or editing the issue and resuming through Draft; a local Block on hosts the sandbox denied names them and its own fix (Exit: blocked, below). +7. **Stopped.** A person applies `pendulum:draft` or closes the issue. Removing `pendulum:objective` also stops an issue for backward compatibility. Nothing lists a stopped Objective for a start (the dispatcher, the local loop's resumes and reviews, the sandbox launcher, the review job). A running stage reads its issue once a minute and on the stop ends every harness pass (`lib/stop.mjs`), records the spend so far and exits with `exit: stopped`; from the stop on it starts no pass, command, push or PR change, and it writes its usage and spend line before any other GitHub call (at two minutes it writes what it knows at once and exits). A pass ended before it reported dollars, or still running, is a run of unknown cost, as on the spend line. A cloud sandbox stage that its launcher process ends instead (its wall clock) records the stage as a run of unknown cost too (`stage.mjs` `killedUsage`), never `max_usd` or another bound, so `daily_usd` names it without counting it. A stop racing the stage's own exit (one being applied, or its merge) ends nothing, and the merge pass reads the issue before any merge, so a stopped Objective never merges; its PR leaves the merge queue and becomes a draft without `pendulum:review`, and its state label and card go back to Queued. The dispatcher does the same for a stopped Objective In review, and for a Running one ten minutes after the stop. A trusted Draft removal continues it after the stop or Block. 8. **Restarted.** A person who can push (or a named maintainer) applies `pendulum:restart`, in any state; anyone else's label comes off with a comment. A running stage stops as in 7; one that missed the label learns of the restart from its record, newer than its start, at its watch and before it pushes or writes its exit. The dispatcher of the Objective's route holds it while a stage of it may run, whatever its state (an Actions work or review job, a sandbox lease, a local loop's live claim; a read that fails counts as may run), for at most 10 minutes from the label; no merge or send-back touches it, and the merge pass reads the issue before any merge. Then it writes a restart record on the issue (the label's time, who applied it, the earlier PR and the branch's last commit, kept across a retry), which says first what the restart discards: the PR with its review, the branch's commits with the command that restores them, and the spend on them; takes the earlier PR out of the queue, deletes `pendulum/` (read back: a ruleset that keeps it Blocks the Objective with the fix), comments on and closes the PR, renames the plan comment's and the parts record's markers, removes the state labels and then the restart label, and queues the Objective: the next run starts from the default branch and the issue's current text. A maintainer comment, a plan comment or a parts record made before the label's time is read by no stage any more (`logic.mjs` `maintainerDecisions`, `handoff.mjs` `planOf`, `partsRecord`). Every retry and rebase count starts over with the new PR and Running stint. Until then nothing starts it: the dispatcher holds it, and the launcher, the review job, the worker and the local loop skip it. ## The task card and the skills @@ -207,8 +207,8 @@ The worker's instructions are a short task card (`plugin/templates/task-card.md` | Allowed | Any file not on the protected list (`.github/`, `CODEOWNERS`, `.agents/skills/`, `.claude/`, `.codex/`, the files the `setup` command names, plus the repository's `protected_paths`), and anything else but what the `setup` command runs (ADAPTERS.md, Setup is trusted like CI). Any command the runner allows. Sub-agents on the pinned model. Network: the hosts the harness's sandbox allows (GitHub, the npm and Yarn registries, plus `allowed_domains`; locally `PENDULUM_LOCAL_DOMAINS`). | | Not allowed | Asking. Editing a test to pass it unless the issue asks. Touching a protected path (the job refuses the commit, Pendulum refuses to push it); a change under `.github/workflows/` is handed over instead (Workflow hand-over, below). A stage answers only for what changes after it starts: what a maintainer pushed to the branch before it, and what a rebase takes from the default branch, are not its own; reverting a maintainer's change is. In a fix pass (after a red, or the answer pass after the review), changing toolchain, lockfile or CI configuration (version pins, package-manager config, including a `pnpm-workspace.yaml` change other than to its `packages` list alone, or one that does not parse, lockfiles, CI files outside `.github/`, containers and devcontainers, git hook managers, a path on the repository's `toolchain_paths`, a file the `setup` or an explicit `install` command names, other than a manifest, lockfile or requirements file it reads, a `package.json` script either runs, and, when either may run a file Pendulum cannot name, any file) that the branch had not changed before the stage's first fix pass, that the plan as it stood then does not name (the plan is read once per stage: a fix pass that edits it widens a later stage's scope, never its own stage's), and that the issue, a maintainer decision, the red's failure window or the comment answered does not name either (a lockfile is in scope when its own manifest beside it is: changed before, named, or changed by the same pass, as when the fix adds a dependency, so `package.json` brings `package-lock.json`, `pnpm-lock.yaml` or `yarn.lock`, `pyproject.toml` brings `uv.lock` or `poetry.lock`, `Cargo.toml` brings `Cargo.lock` (`lib/logic.mjs` `LOCK_PAIRS` lists every pair), and nothing else; in a workspace, a member's manifest changed before or by the same pass brings the workspace's root lockfile, and only it: `pnpm-lock.yaml` for a `pnpm-workspace.yaml`, the npm, yarn or bun lockfile for `package.json` `workspaces`, `uv.lock` for `[tool.uv.workspace]`, `Cargo.lock` for Cargo `[workspace]`, members as that declaration listed them when the fix passes began, exclusions honoured; a lockfile changed without its manifest or a member's in scope is refused), unless the fence check (`lib/fence-check.mjs`), a decision call given the failing checks' lead lines, the comments answered, the plan and the pass's textual diff to the file (up to 32 KiB), judges that file's change part of fixing the red rather than weakening or sidestepping the check. It is asked only about a lockfile that exists as a regular file both before the fix passes and at the pass's head (one the pass creates or deletes can change which install `install: auto` runs), at most 10 files each time the fence is read, and no file again in a stage once it has been refused twice (the same change is never asked about twice); a lockfile the setup command's install reads is judged too, as its manifest beside it in scope already lets it go. It is never asked about anything else (version pins, CI files, git hook managers, containers and devcontainers, build-tool wrappers, package-manager configuration, a `toolchain_paths` file, a protected path, or what the `setup` or `install` command names or runs), nor about a binary or empty change; it reads its verdict at the confidence floor, never under 0.7 whatever `triage_min_confidence` says; and with no decider, no answer or any other verdict the file stays refused: the pass gets one turn to put those files back, and what it keeps is refused (Pendulum pushes none of it, posts no PR body, reply or thread resolution from that pass, and the stage Blocks with the files named, as Pendulum's or an outage's when the fence check gave no answer on every one of them). A turn that puts them back and asks a Question in its exit record ends the stage with that Question; no further fix pass runs. Any write to GitHub: no push, PR, comment, reply or label. | | Exit: delivered | PR open and not a draft; validation green, or (the work stage, with required checks) its head handed to the review with its checks running; reviewer pass done. The merge queue takes it. | -| Exit: question | The worker hit an assumption that would change or remove an existing public contract, contradict a recorded decision or grant new access (a permission, a credential, a newly exposed service); any other addition that leaves every existing use working is an assumption. Each question in the exit record names its test (`contract`, `decision` or `access`) and the existing contract, the decision or the access granted; a question exit that names none is checked once by the harness, which keeps what meets a test and records the rest as assumptions. The PR stays a draft with the question in its body; everything else is finished. The card moves to In review with a question marker; the queue continues. A human answers in a comment, review or line comment on the PR or the issue and marks the PR ready; the review job runs, and its answer pass applies what was said since the question even when the PR was already reviewed, and the commits it makes for it get a reviewer pass before the merge; with nothing new, the PR goes back to a Question. On Actions, when a maintainer both answers and marks the PR ready while the review job that raised the Question is still running, that job leaves the PR ready, and the review job the ready mark started applies the answer. Comments by people with write access reach every worker, reviewer and answer pass as the maintainers' decisions. One Question comes before the work: Pendulum works in one repository per Objective, so a plan that needs a change in another repository (its `Needs-Repository: OWNER/NAME` line) stops after the plan (Pendulum stops the harness when the line appears in its plan.md, read every two minutes), and Pendulum runs no validation or fix pass and asks on the issue, naming the repository and how to answer: split the Objective into one per repository and re-apply the label, or say in a comment on the issue how to do the work in this repository alone (not by marking a PR ready). A maintainer's comment on the issue after a Question asked there (one with no PR, or the plan-time Question) puts the Objective back in the queue at the dispatcher's next tick on every route (`dispatch.mjs`; on the cloud sandbox the comment's own launch does it first), and the worker runs again with it, when the answer check lets it through (`lib/answer-check.mjs`). The answer check is a decision call (below): given the Question as Pendulum's notice on the issue asked it and each writer comment since, oldest first, do the comments give a decision on the question asked, so that the work can continue? Only `no_decision` at the confidence floor or more (Red-check triage, below) keeps the Question open; a decision, a lower confidence, no answer or no decider resumes the work, as a writer's comment always did. The newest comment's version (an edit is a new one) is what is judged, and each verdict is kept on the issue by Pendulum's own login: a decision as a short record, a no decision as a notice saying the comment does not answer, itself a Question notice. So no version is judged twice, on any route, and one judged no decision never resumes the Question. The dispatcher and the launcher have no stage harness, so they ask only with an AI Gateway key (on Actions the dispatch job never has one; the launch job does), and a comment that does not answer then starts no stage. Otherwise the work stage the comment resumes asks first thing, once its decider exists and before its branch, its Running mark, setup, install, the hand-off or the relay, on its own decider (the gateway with a key, else its harness); on a no decision it puts the Objective back to Question and posts that notice, or says the one already kept again, dated after the label, and a notice that cannot be written Blocks. A stage that resumes no Question (a send-back, a delivered or Blocked Objective, a re-applied label: a person's go) asks nothing. A Question its PR asks is still answered by the comment and the ready mark together, unjudged. Which of the two forms a Question has is one decision (`logic.mjs` `questionForm`): it chooses the notice's instruction and is written in the notice's marker, from which the dispatcher reads it. A person's ready mark on the PR while the Objective is Queued or Running starts no review: its work stage owns the branch. An issue body that names another repository for Pendulum to change (its `Pendulum-Repository: OWNER/NAME` line) is asked before any harness runs, and is answered only by taking the line out of the body: while it stays, each rerun asks again, with no harness started. A value that is no OWNER/NAME (`none`, `N/A`, a parenthesis) is no need, and a repository the plan needs is not asked about again once the maintainers' comments since Pendulum asked answer how to handle it. That is the plan-answer check (`lib/plan-answer.mjs`), a decision call (below) on triage's model and confidence floor (Red-check triage, below), given Pendulum's question line for the repository and each maintainer comment since the ask: `answered` at the floor or more answers it, `open` at the floor or more leaves it asked; with no verdict or no decider, a comment that names the repository answers it. | -| Exit: blocked | Validation red after a fix pass that made no progress (`lib/fix-progress.mjs`; no fixed count of passes: the loop goes on while each fix pass makes progress, within `max_usd` and the stage's wall clock). A red triage reads as a flake is rerun first (Red-check triage, below), so only a red that stands is judged. After a fix pass, the next red is judged against the red the pass was handed. Its failing set is the failed check runs (a roll-up required check with no failure line of its own left out: it only repeats the jobs it gathers) or the failing commands. A pass that committed nothing is no progress; so is the same set with each job failing the same way, the same signature and the same folded failure lines as many times each (the signature is the set of folded lines, so it alone cannot tell three failing tests from one; folding keeps a duration that differs from counting), and so is a red equal by signature to any the stage has seen before, in any of its validation loops, jobs with no failure line matched by name (A, then B, then A again Blocks, naming both). A different or smaller set is progress only when every job that failed before now passes (a job skipped, not run or missing, as when a build break hides the tests, is no pass). Anything else is a decision call (`decision_route`, on triage's model and confidence floor) asking whether the pass moved the branch closer to green, given each red's failing names and failure lines and the `--stat` of the pass's own commits (first-parent, so a catch-up merge brings in nothing of the default branch); with no decider it is no progress. A decider that gives no answer leaves the judgement unmade: the stage Blocks with the cause `pendulum` (`outage` when the vendor is unavailable or throttled), saying so; the stage harness's usage limit met by that call ends the stage on the limit (paused locally, held or Blocked `provider-quota` elsewhere). What bounds the loop is `max_usd` and the wall clock; a decider that keeps answering `closer` runs until one of them ends it. The Block names the red (`validation red on Pendulum's pass (): the fix pass before it made no progress: ; failing: ()`, or `could not be judged for progress`). A red on a merge of the default branch Pendulum made itself before a push (Review and merge, below) is not the change's: it gets its fix pass unjudged, decided on the commit id Pendulum recorded for its merge; each fix run after a required-check red gets every failing job's whole log as a file (aggregates included, required jobs first, none left out for an optional one; at most ten) and the two-dot diff from the PR's last green head (or why none could be made), and, as evidence and never as an instruction, how many of the default branch's newest runs of each job are red and their failure lines beside this run's; a red whose every failing job fails the same way steadily on the default branch (the same job with the same failure, on its newest run there and on at least two of its newest three, attempts included) is handed back at once as a base failure (`base failure: fail the same way on @`), with no fix run; "the same failure" is the same failure signature (failure lines and the repository files they point at) when both runs have one, and otherwise, when either has none or the two differ in the same failed step, a same-failure decision call (Red-check triage, below), which counts only at the confidence floor and is not asked when the head points at the change (triage read a failing job as the change's at the floor, or a failure names a file or test the PR changes: then the signature alone decides); a red that is all the default branch's but for such a call that got no answer gets no fix run and Blocks as Pendulum's or, for the decider's outage, as an outage, naming what could not be judged (on the merge queue it is enqueued again, `unjudged`); a single red run on the default branch (a flake, an outage) hands nothing back; a required check whose Actions job GitHub never started (completed as failed with no step and no runner: a billing lock, a spending limit, a runner label nothing serves; the job itself, or one a failing required aggregate gathers when every failing job that aggregate gathers never started) Blocks at once with no triage, rerun or fix run (`GitHub did not start the required job : `), decided on those fields and never on the annotation's words; a running required check is waited for while it makes progress, within the stage's wall clock, read as the merge queue's commit is (Review and merge, below): one whose current step has run past max(3 × that step's normal duration, that duration + 15 minutes) has hung, and the wait ends there unfinished, the Block naming the step and its times (`no progress: …`) and saying that re-applying the label waits for that head up to the stage's wall clock: Pendulum records the Block on the PR (``), and a later stage on that head judges no hang (for a change that makes a step slower on purpose); one with no history to judge it by (a new step, a check that is no Actions job, a job Pendulum cannot read, and every check on the local route, where Pendulum reads no job steps) is waited for up to the merge queue rule's `check_response_timeout_minutes` when an active ruleset on the default branch sets one, else the stage's wall clock; its job is read only once it could have hung, and again only when that reading could have changed the answer (a job that could not be read, likewise); a required check that is not running (queued, waiting, or not reported, with no upstream job of it running) for 60 minutes ends the wait, as the not-started bound below; required commit statuses are read beside the check runs, while a required name has no check run: a pending status is a check running, a failing one a red; the reads are a minute apart for the first hour, then back off to five, and are conditional (an unchanged page answers 304, outside GitHub's rate limit); a wait on the required checks that ends with none failed and some not finished is no red at all: no triage, no fix run and no pass counted; read on structure from the head's check runs and workflow runs, a required check not started yet (its check run still queued with no runner, in a workflow run still going or one that completed; or, with no check run, the workflow that produces it queued on the head, or never created) is waited for in the stage, on every route, up to 60 minutes or the stage's wall clock less 5 minutes, the reads backing off from one minute to five; one that starts during that wait and is still running at its end is waited for as any running check; still not started, the stage Blocks naming the run, how long it sat and who has not started it: GitHub (`GitHub has not started the required check(s) on : workflow run (run ) queued min with no job started (infrastructure, not this change)`), the service whose app owns the check run (` has not started …`), or a run `pending` behind the repository's own concurrency group (`The repository's concurrency group holds …`); the workflow that produces a check is the one of the repository's workflows (read at the head) with a job reporting that name (its `name`, a `${{ }}` in it standing for any text, else its id; a matrix job adds ` (…)`; a job calling a reusable workflow reports ` / `, read from this repository, any name under the caller for another repository's), else the workflow of that check's run on the PR's last green head or the default branch's newest commits; a queued run of another workflow is not that check's; a check is filtered out, and Blocks at once naming the filter (`run the check on every change, or stop requiring it`), only when that is certain: every workflow that produces it has an `on.pull_request` `paths` or `paths-ignore` that skips the PR's changed files (read, and not none), `pull_request` is the only trigger that can start it on the head (beside `merge_group`, `schedule`, `workflow_call`, `workflow_run` and `release`), and its patterns use only `*`, `**` and `!` (GitHub's `?`, `+` and `[…]` are not guessed at); anything less certain, a companion `paths-ignore` workflow of the same check included, is waited for, and the Block's reason says the path filter may skip the change; each workflow file is read once per stage; a failed read of the check runs keeps the last good reading once one has succeeded, and the wait goes on to its own deadline (with none yet, it ends at the first 15 minutes as before); a check whose producing workflow run ended `startup_failure`, or was cancelled before the job that reports it existed, Blocks naming that run and its conclusion, never the check names, as soon as every workflow run on the head has completed and each run that produces the check ended so (cancelled counts only with no check run in its suite); a check no workflow on the head produces (`check the required check names`, naming each run on the head and how it ended), or whose workflow's path filter skips the change, Blocks as soon as every workflow run on the head has completed, when nothing else may still report it: the default branch's ruleset binds the check to Actions, or binds it to no app and no check suite on the head of any app but Actions is still going (suites that cannot be read count as going; a check bound to another app never ends the wait early); a name older commits got as a commit status (read from the PR's last green head and the default branch's newest commits, as for check runs) is that status's service's to post, and is waited for as not started (`the service posting it has not started …`); no workflow at the head runs `on: workflow_run` (a workflow file that cannot be read, or a reusable workflow it calls through `uses: ./…` that cannot be read, counts as one); and no triage rerun is awaited; otherwise the 60 minutes with nothing running end the wait; the reading is classified again only when the head's runs or suites read differently; a check waiting for a deployment approval, one still running, and one no workflow on the head produces (`check the required check names`) Block at once with that reason, never as validation red; a last red whose triage read every failing job as a flake but whose rerun GitHub refused Blocks saying so, with triage's verdicts, the refusal and the remedy (rerun the failed jobs, or give the token Actions write: the workflow's `actions: write` on Actions, the local token's Actions read and write); a fix pass that commits nothing leaves the red head as it was, so its checks are not read again as a second red and no pass is counted: the failed jobs are rerun once for that head (no question asked, with or without a decider) only when nothing reads the red as the change's (no `change_caused` verdict on that head, no failure naming what the PR changes, no failure signature already rerun on the Objective, at most ten jobs) and each failing job either got a model verdict on that head or failed on GitHub's side (below), and when a rerun is not made for any of those reasons, already made on that head or red again and the red is the work's (not one whose every failed job failed on GitHub's side, below, before and after the head's rerun), the Objective gets one fresh worker pass before it Blocks. The red it is given is the one as it stands after the head's rerun, when one was made (it can fail another way than the red the fix pass had): read like any red, so one the default branch fails the same way is handed back as a base failure with no fresh pass, and the pass's scope fence names it as a fix pass's does. The pass is a new session, never a resume, given the task card, that red's failing jobs' own failure lines and outputs as a fix pass gets them, and the fix pass's last message as evidence; it runs once per head in a stage and is not counted as a pass. It runs only when what is left can carry it, read after the rerun's red: with `max_usd` set, at least what the fix pass cost (Codex has no in-run cap, so a smaller remainder would be overspent), and wall clock for the fix pass's own time, the head's checks' wait and two minutes for the exit (a minute at least). The progress comment says it ran, or why not. What it commits is validated as the next pass, judged for progress against the red it was handed, and the stage's session stays the fresh pass's; a Block for validation red after it then names it (`…; a fresh worker pass followed the fix pass that changed nothing on `). A fresh pass that commits nothing, read on the checkout's HEAD before and after it, hands the stage's session back to the worker's thread, a capped one included. A rerun refused, a red on GitHub's side, a fresh pass that commits nothing or one not given Blocks (`the fix pass changed nothing, so the red on is unchanged (); …`, `the fix pass and the fresh worker pass after it changed nothing, …` when one ran, then the refusal or the remedy, and `; no fresh worker pass: ` when none was given); a fresh pass that reaches its dollar or time cap Blocks the same way, the work's, ending `; the fresh worker pass after it reached the dollar cap` (or `time cap`), unless it committed: then the Block says `the fix pass changed nothing on (); the fresh worker pass committed and reached the dollar cap; not validated`, the stage pushes that commit unvalidated and its session stays the fresh pass's; the Block's quoted output leads with the red required checks (`PENDULUM_CI_CHECKS`, else the ruleset's), each named ` (required check)` with its own failure lines; a required roll-up with none of its own (an aggregate) is quoted from a failing job it gathers (` (required check), from `): the jobs its job `needs` in its workflow file at the run's head, directly or through jobs between them (a skipped one included), a run ` / …` counting as the job that calls a reusable workflow, else (no file, or none of those with a failure line) every failing job of its run, one whose job cannot fail without failing the run first (its `continue-on-error`, a `${{ }}` expression of at most 1 KB evaluated over the leg's matrix values (the leg found by its check name: its values in a ` (…)` suffix, or a job name with `${{ }}` evaluated the same way for each leg) with GitHub's own expression library, `@actions/expressions`; unknown when it reads any other context or calls a function); the other failing jobs follow, each one no required check counts marked `not required`: a required check, a roll-up or not, counts the failing jobs of its own run that its job needs (read from that same file when its run has other failing jobs), less those that may fail without failing the run, and when the file cannot say, none of its run's jobs is called not required; reviewer findings still open after the answer rounds (Review and merge, below); the answer to a review pass on commits the answer gate held, held again (Review and merge, below); a send-back's rebase that makes no progress or reached its bound (Merge, above); dollar or time cap reached; worker process died twice; the model provider refused a harness call outright (a 4xx other than a timeout, conflict, too early or rate limit, or a quota, billing, authentication or permission type or code, read from the harness's own structured error: Claude Code's result `api_error_status`, Codex's `turn.failed` JSON error body, Copilot's `session.error`; never from the message's words), which is never counted as a death and Blocks at once (a resumed pass refused with a 400, 413 or 422 and no such type or code first runs once as a fresh session with the full card, where the pass has one, since its session's own request may be what was refused; the fresh pass's refusal stands) naming the harness, the status, type and code and the provider's message shortened (` was refused by its provider (HTTP 400 ): …`), the fix being the credential's account or the settings; doctor's `--probe` fails on the same refusal. Draft PR, card to Blocked, one comment with the reason, the fix, and whether to resume or restart, decided on the Block's cause: any cause but `work` says resume (re-apply `pendulum:objective`, which goes on from the branch and PR), not restart; `work` says resume once the cause is fixed and restart only when the work itself must be redone; each names what a restart discards (the PR, delivered or not, with its review, the branch's commits and the spend on them). A restart that could not finish says how to keep the work instead, and an untrusted author's Block says neither gets past it. A worker's own reason, like a Question's, is shortened past 200 characters on a word boundary and ends in `…`. A worker that stops because its sandbox denied a host it cannot do without lists the host names in its exit record's `deniedHosts` (values that are not a DNS host name are dropped; at most ten); in local mode the comment names each host the sandboxes do not already allow and gives that fix instead of a push or an edit: add them to `PENDULUM_LOCAL_DOMAINS`, then re-apply `pendulum:objective`. Pendulum never allows a host itself. | +| Exit: question | The worker hit an assumption that would change or remove an existing public contract, contradict a recorded decision or grant new access (a permission, a credential, a newly exposed service); any other addition that leaves every existing use working is an assumption. Each question in the exit record names its test (`contract`, `decision` or `access`) and the existing contract, the decision or the access granted; a question exit that names none is checked once by the harness, which keeps what meets a test and records the rest as assumptions. The PR stays a draft with the question in its body; everything else is finished. The card moves to In review with a question marker; the queue continues. A human answers in a comment, review or line comment on the PR or the issue and marks the PR ready; the review job runs, and its answer pass applies what was said since the question even when the PR was already reviewed, and the commits it makes for it get a reviewer pass before the merge; with nothing new, the PR goes back to a Question. On Actions, when a maintainer both answers and marks the PR ready while the review job that raised the Question is still running, that job leaves the PR ready, and the review job the ready mark started applies the answer. Comments by people with write access reach every worker, reviewer and answer pass as the maintainers' decisions. One Question comes before the work: Pendulum works in one repository per Objective, so a plan that needs a change in another repository (its `Needs-Repository: OWNER/NAME` line) stops after the plan (Pendulum stops the harness when the line appears in its plan.md, read every two minutes), and Pendulum runs no validation or fix pass and asks on the issue, naming the repository and how to answer: split the Objective into one per repository and resume through Draft, or say in a comment on the issue how to do the work in this repository alone (not by marking a PR ready). A maintainer's comment on the issue after a Question asked there (one with no PR, or the plan-time Question) puts the Objective back in the queue at the dispatcher's next tick on every route (`dispatch.mjs`; on the cloud sandbox the comment's own launch does it first), and the worker runs again with it, when the answer check lets it through (`lib/answer-check.mjs`). The answer check is a decision call (below): given the Question as Pendulum's notice on the issue asked it and each writer comment since, oldest first, do the comments give a decision on the question asked, so that the work can continue? Only `no_decision` at the confidence floor or more (Red-check triage, below) keeps the Question open; a decision, a lower confidence, no answer or no decider resumes the work, as a writer's comment always did. The newest comment's version (an edit is a new one) is what is judged, and each verdict is kept on the issue by Pendulum's own login: a decision as a short record, a no decision as a notice saying the comment does not answer, itself a Question notice. So no version is judged twice, on any route, and one judged no decision never resumes the Question. The dispatcher and the launcher have no stage harness, so they ask only with an AI Gateway key (on Actions the dispatch job never has one; the launch job does), and a comment that does not answer then starts no stage. Otherwise the work stage the comment resumes asks first thing, once its decider exists and before its branch, its Running mark, setup, install, the hand-off or the relay, on its own decider (the gateway with a key, else its harness); on a no decision it puts the Objective back to Question and posts that notice, or says the one already kept again, dated after the label, and a notice that cannot be written Blocks. A stage that resumes no Question (a send-back, a delivered or Blocked Objective, or a person's Draft removal) asks nothing. A Question its PR asks is still answered by the comment and the ready mark together, unjudged. Which of the two forms a Question has is one decision (`logic.mjs` `questionForm`): it chooses the notice's instruction and is written in the notice's marker, from which the dispatcher reads it. A person's ready mark on the PR while the Objective is Queued or Running starts no review: its work stage owns the branch. An issue body that names another repository for Pendulum to change (its `Pendulum-Repository: OWNER/NAME` line) is asked before any harness runs, and is answered only by taking the line out of the body: while it stays, each rerun asks again, with no harness started. A value that is no OWNER/NAME (`none`, `N/A`, a parenthesis) is no need, and a repository the plan needs is not asked about again once the maintainers' comments since Pendulum asked answer how to handle it. That is the plan-answer check (`lib/plan-answer.mjs`), a decision call (below) on triage's model and confidence floor (Red-check triage, below), given Pendulum's question line for the repository and each maintainer comment since the ask: `answered` at the floor or more answers it, `open` at the floor or more leaves it asked; with no verdict or no decider, a comment that names the repository answers it. | +| Exit: blocked | Validation red after a fix pass that made no progress (`lib/fix-progress.mjs`; no fixed count of passes: the loop goes on while each fix pass makes progress, within `max_usd` and the stage's wall clock). A red triage reads as a flake is rerun first (Red-check triage, below), so only a red that stands is judged. After a fix pass, the next red is judged against the red the pass was handed. Its failing set is the failed check runs (a roll-up required check with no failure line of its own left out: it only repeats the jobs it gathers) or the failing commands. A pass that committed nothing is no progress; so is the same set with each job failing the same way, the same signature and the same folded failure lines as many times each (the signature is the set of folded lines, so it alone cannot tell three failing tests from one; folding keeps a duration that differs from counting), and so is a red equal by signature to any the stage has seen before, in any of its validation loops, jobs with no failure line matched by name (A, then B, then A again Blocks, naming both). A different or smaller set is progress only when every job that failed before now passes (a job skipped, not run or missing, as when a build break hides the tests, is no pass). Anything else is a decision call (`decision_route`, on triage's model and confidence floor) asking whether the pass moved the branch closer to green, given each red's failing names and failure lines and the `--stat` of the pass's own commits (first-parent, so a catch-up merge brings in nothing of the default branch); with no decider it is no progress. A decider that gives no answer leaves the judgement unmade: the stage Blocks with the cause `pendulum` (`outage` when the vendor is unavailable or throttled), saying so; the stage harness's usage limit met by that call ends the stage on the limit (paused locally, held or Blocked `provider-quota` elsewhere). What bounds the loop is `max_usd` and the wall clock; a decider that keeps answering `closer` runs until one of them ends it. The Block names the red (`validation red on Pendulum's pass (): the fix pass before it made no progress: ; failing: ()`, or `could not be judged for progress`). A red on a merge of the default branch Pendulum made itself before a push (Review and merge, below) is not the change's: it gets its fix pass unjudged, decided on the commit id Pendulum recorded for its merge; each fix run after a required-check red gets every failing job's whole log as a file (aggregates included, required jobs first, none left out for an optional one; at most ten) and the two-dot diff from the PR's last green head (or why none could be made), and, as evidence and never as an instruction, how many of the default branch's newest runs of each job are red and their failure lines beside this run's; a red whose every failing job fails the same way steadily on the default branch (the same job with the same failure, on its newest run there and on at least two of its newest three, attempts included) is handed back at once as a base failure (`base failure: fail the same way on @`), with no fix run; "the same failure" is the same failure signature (failure lines and the repository files they point at) when both runs have one, and otherwise, when either has none or the two differ in the same failed step, a same-failure decision call (Red-check triage, below), which counts only at the confidence floor and is not asked when the head points at the change (triage read a failing job as the change's at the floor, or a failure names a file or test the PR changes: then the signature alone decides); a red that is all the default branch's but for such a call that got no answer gets no fix run and Blocks as Pendulum's or, for the decider's outage, as an outage, naming what could not be judged (on the merge queue it is enqueued again, `unjudged`); a single red run on the default branch (a flake, an outage) hands nothing back; a required check whose Actions job GitHub never started (completed as failed with no step and no runner: a billing lock, a spending limit, a runner label nothing serves; the job itself, or one a failing required aggregate gathers when every failing job that aggregate gathers never started) Blocks at once with no triage, rerun or fix run (`GitHub did not start the required job : `), decided on those fields and never on the annotation's words; a running required check is waited for while it makes progress, within the stage's wall clock, read as the merge queue's commit is (Review and merge, below): one whose current step has run past max(3 × that step's normal duration, that duration + 15 minutes) has hung, and the wait ends there unfinished, the Block naming the step and its times (`no progress: …`) and saying that resuming through Draft waits for that head up to the stage's wall clock: Pendulum records the Block on the PR (``), and a later stage on that head judges no hang (for a change that makes a step slower on purpose); one with no history to judge it by (a new step, a check that is no Actions job, a job Pendulum cannot read, and every check on the local route, where Pendulum reads no job steps) is waited for up to the merge queue rule's `check_response_timeout_minutes` when an active ruleset on the default branch sets one, else the stage's wall clock; its job is read only once it could have hung, and again only when that reading could have changed the answer (a job that could not be read, likewise); a required check that is not running (queued, waiting, or not reported, with no upstream job of it running) for 60 minutes ends the wait, as the not-started bound below; required commit statuses are read beside the check runs, while a required name has no check run: a pending status is a check running, a failing one a red; the reads are a minute apart for the first hour, then back off to five, and are conditional (an unchanged page answers 304, outside GitHub's rate limit); a wait on the required checks that ends with none failed and some not finished is no red at all: no triage, no fix run and no pass counted; read on structure from the head's check runs and workflow runs, a required check not started yet (its check run still queued with no runner, in a workflow run still going or one that completed; or, with no check run, the workflow that produces it queued on the head, or never created) is waited for in the stage, on every route, up to 60 minutes or the stage's wall clock less 5 minutes, the reads backing off from one minute to five; one that starts during that wait and is still running at its end is waited for as any running check; still not started, the stage Blocks naming the run, how long it sat and who has not started it: GitHub (`GitHub has not started the required check(s) on : workflow run (run ) queued min with no job started (infrastructure, not this change)`), the service whose app owns the check run (` has not started …`), or a run `pending` behind the repository's own concurrency group (`The repository's concurrency group holds …`); the workflow that produces a check is the one of the repository's workflows (read at the head) with a job reporting that name (its `name`, a `${{ }}` in it standing for any text, else its id; a matrix job adds ` (…)`; a job calling a reusable workflow reports ` / `, read from this repository, any name under the caller for another repository's), else the workflow of that check's run on the PR's last green head or the default branch's newest commits; a queued run of another workflow is not that check's; a check is filtered out, and Blocks at once naming the filter (`run the check on every change, or stop requiring it`), only when that is certain: every workflow that produces it has an `on.pull_request` `paths` or `paths-ignore` that skips the PR's changed files (read, and not none), `pull_request` is the only trigger that can start it on the head (beside `merge_group`, `schedule`, `workflow_call`, `workflow_run` and `release`), and its patterns use only `*`, `**` and `!` (GitHub's `?`, `+` and `[…]` are not guessed at); anything less certain, a companion `paths-ignore` workflow of the same check included, is waited for, and the Block's reason says the path filter may skip the change; each workflow file is read once per stage; a failed read of the check runs keeps the last good reading once one has succeeded, and the wait goes on to its own deadline (with none yet, it ends at the first 15 minutes as before); a check whose producing workflow run ended `startup_failure`, or was cancelled before the job that reports it existed, Blocks naming that run and its conclusion, never the check names, as soon as every workflow run on the head has completed and each run that produces the check ended so (cancelled counts only with no check run in its suite); a check no workflow on the head produces (`check the required check names`, naming each run on the head and how it ended), or whose workflow's path filter skips the change, Blocks as soon as every workflow run on the head has completed, when nothing else may still report it: the default branch's ruleset binds the check to Actions, or binds it to no app and no check suite on the head of any app but Actions is still going (suites that cannot be read count as going; a check bound to another app never ends the wait early); a name older commits got as a commit status (read from the PR's last green head and the default branch's newest commits, as for check runs) is that status's service's to post, and is waited for as not started (`the service posting it has not started …`); no workflow at the head runs `on: workflow_run` (a workflow file that cannot be read, or a reusable workflow it calls through `uses: ./…` that cannot be read, counts as one); and no triage rerun is awaited; otherwise the 60 minutes with nothing running end the wait; the reading is classified again only when the head's runs or suites read differently; a check waiting for a deployment approval, one still running, and one no workflow on the head produces (`check the required check names`) Block at once with that reason, never as validation red; a last red whose triage read every failing job as a flake but whose rerun GitHub refused Blocks saying so, with triage's verdicts, the refusal and the remedy (rerun the failed jobs, or give the token Actions write: the workflow's `actions: write` on Actions, the local token's Actions read and write); a fix pass that commits nothing leaves the red head as it was, so its checks are not read again as a second red and no pass is counted: the failed jobs are rerun once for that head (no question asked, with or without a decider) only when nothing reads the red as the change's (no `change_caused` verdict on that head, no failure naming what the PR changes, no failure signature already rerun on the Objective, at most ten jobs) and each failing job either got a model verdict on that head or failed on GitHub's side (below), and when a rerun is not made for any of those reasons, already made on that head or red again and the red is the work's (not one whose every failed job failed on GitHub's side, below, before and after the head's rerun), the Objective gets one fresh worker pass before it Blocks. The red it is given is the one as it stands after the head's rerun, when one was made (it can fail another way than the red the fix pass had): read like any red, so one the default branch fails the same way is handed back as a base failure with no fresh pass, and the pass's scope fence names it as a fix pass's does. The pass is a new session, never a resume, given the task card, that red's failing jobs' own failure lines and outputs as a fix pass gets them, and the fix pass's last message as evidence; it runs once per head in a stage and is not counted as a pass. It runs only when what is left can carry it, read after the rerun's red: with `max_usd` set, at least what the fix pass cost (Codex has no in-run cap, so a smaller remainder would be overspent), and wall clock for the fix pass's own time, the head's checks' wait and two minutes for the exit (a minute at least). The progress comment says it ran, or why not. What it commits is validated as the next pass, judged for progress against the red it was handed, and the stage's session stays the fresh pass's; a Block for validation red after it then names it (`…; a fresh worker pass followed the fix pass that changed nothing on `). A fresh pass that commits nothing, read on the checkout's HEAD before and after it, hands the stage's session back to the worker's thread, a capped one included. A rerun refused, a red on GitHub's side, a fresh pass that commits nothing or one not given Blocks (`the fix pass changed nothing, so the red on is unchanged (); …`, `the fix pass and the fresh worker pass after it changed nothing, …` when one ran, then the refusal or the remedy, and `; no fresh worker pass: ` when none was given); a fresh pass that reaches its dollar or time cap Blocks the same way, the work's, ending `; the fresh worker pass after it reached the dollar cap` (or `time cap`), unless it committed: then the Block says `the fix pass changed nothing on (); the fresh worker pass committed and reached the dollar cap; not validated`, the stage pushes that commit unvalidated and its session stays the fresh pass's; the Block's quoted output leads with the red required checks (`PENDULUM_CI_CHECKS`, else the ruleset's), each named ` (required check)` with its own failure lines; a required roll-up with none of its own (an aggregate) is quoted from a failing job it gathers (` (required check), from `): the jobs its job `needs` in its workflow file at the run's head, directly or through jobs between them (a skipped one included), a run ` / …` counting as the job that calls a reusable workflow, else (no file, or none of those with a failure line) every failing job of its run, one whose job cannot fail without failing the run first (its `continue-on-error`, a `${{ }}` expression of at most 1 KB evaluated over the leg's matrix values (the leg found by its check name: its values in a ` (…)` suffix, or a job name with `${{ }}` evaluated the same way for each leg) with GitHub's own expression library, `@actions/expressions`; unknown when it reads any other context or calls a function); the other failing jobs follow, each one no required check counts marked `not required`: a required check, a roll-up or not, counts the failing jobs of its own run that its job needs (read from that same file when its run has other failing jobs), less those that may fail without failing the run, and when the file cannot say, none of its run's jobs is called not required; reviewer findings still open after the answer rounds (Review and merge, below); the answer to a review pass on commits the answer gate held, held again (Review and merge, below); a send-back's rebase that makes no progress or reached its bound (Merge, above); dollar or time cap reached; worker process died twice; the model provider refused a harness call outright (a 4xx other than a timeout, conflict, too early or rate limit, or a quota, billing, authentication or permission type or code, read from the harness's own structured error: Claude Code's result `api_error_status`, Codex's `turn.failed` JSON error body, Copilot's `session.error`; never from the message's words), which is never counted as a death and Blocks at once (a resumed pass refused with a 400, 413 or 422 and no such type or code first runs once as a fresh session with the full card, where the pass has one, since its session's own request may be what was refused; the fresh pass's refusal stands) naming the harness, the status, type and code and the provider's message shortened (` was refused by its provider (HTTP 400 ): …`), the fix being the credential's account or the settings; doctor's `--probe` fails on the same refusal. Draft PR, card to Blocked, one comment with the reason, the fix, and whether to resume or restart, decided on the Block's cause: any cause but `work` says resume (resume through Draft to continue from the branch and PR), not restart; `work` says resume once the cause is fixed and restart only when the work itself must be redone; each names what a restart discards (the PR, delivered or not, with its review, the branch's commits and the spend on them). A restart that could not finish says how to keep the work instead, and an untrusted author's Block says neither gets past it. A worker's own reason, like a Question's, is shortened past 200 characters on a word boundary and ends in `…`. A worker that stops because its sandbox denied a host it cannot do without lists the host names in its exit record's `deniedHosts` (values that are not a DNS host name are dropped; at most ten); in local mode the comment names each host the sandboxes do not already allow and gives that fix instead of a push or an edit: add them to `PENDULUM_LOCAL_DOMAINS`, then resume through Draft. Pendulum never allows a host itself. | The Question exit does not stop the Objective's other work or the queue, and costs the worker nothing to raise, so it is raised only when the card's test is met. @@ -223,7 +223,7 @@ Workflow hand-over. Pendulum never pushes a change under `.github/workflows/`, o Trust. Pendulum acts on an Objective's text only when the issue's author, its last editor once the body was edited, and the person who made its latest rename once the title was renamed (that rename naming the title now) can push or are pinned maintainers. The worker and the review job check it before any harness on every route (Actions, local mode, a cloud-sandbox stage), acting on the title and body read with those people; a session reads the issue only through `pendulum issue`, and `deliver` and `post-review` check it again. Otherwise the stage Blocks before a harness sees the text. Pendulum acts on a marker (validated, rebase, review, spend, decisions-read, a local claim) only from its own login or from a person with push access. Its own login comes from its token, never from a comment's author: the App's bot on Actions, the token's owner in local mode. No other App counts, the job token's `github-actions[bot]` included. The workflow's `notify` and `maintainers` are written `login#id` and trusted by the numeric id, so a login renamed away is a stranger; doctor warns about a bare one and names the id to add. -Edits. The plan comment records the Objective text its plan was made from, on its marker line, written only by Pendulum: the SHA-256 of the title and body (line ends as LF, trailing whitespace dropped, so a save that changes nothing else is no edit), the time of the latest `pendulum:objective` label event, read before the text, when a work stage last started from that text, the text itself (title, body and harness, model and host labels: an edit's before) and the edit check's verdict for each later text, by its hash, as GitHub's 65,536-character limit leaves room for them, counted in UTF-8 bytes: the verdicts go first (they are asked again), the text only when it does not fit alone. In the record, `<` and `>` are JSON escapes, so no text in it closes the comment. A write of the plan comment keeps the verdicts another process wrote on it for the same text since this one read it. The plan comment read is the newest written by Pendulum's own login or a person who can push (local mode writes as its developer). No other App's comment counts, `github-actions[bot]` included: it never stands in for that comment. Only when there is none, the earliest App comment carrying the marker (Pendulum's App, read from a local process) counts for its time, so the stage decides on edit times (below) instead of on no plan; its text and any record in it are never read. After the trust check, each work stage and review job compares the text it read with that record before anything is set up for it, and the merge pass compares the text as it stands before it merges or enqueues, and while the PR waits in the merge queue (it is taken out of it). The same text goes on. A changed text is first judged by the edit check (`lib/edit-check.mjs`), a decision call asked once per distinct new text, its verdict written on the record: given the title and body before and after, does the edit change what has to be built? `wording` (typos, formatting, rewording only) at the confidence floor (Red-check triage, below) keeps the plan and the code: the stage goes on as on the same text, says so in one line on its progress comment (the verdict, the decider that gave it and its confidence), and the record still names the text the plan was made from, so the next edit is judged against that text too, and a work pass paused in local mode is held to that text (`lib/continue.mjs`) and continues. Any other answer, or none, is the rule below. A harness, model or host label added, removed or changed is a changed requirement as it stands, never asked about. The edit check is asked only on text that passed the trust check (its author, last editor and latest title renamer). A record without its text (one written before the record kept it, or one too long for the comment), a text whose hash is not the record's, a text too long to show the decider whole, or no decider (`decision_route` off, or `gateway` with no key) is never judged; with `decision_route` off a verdict the record keeps is not used either, and any verdict is used only after the same checks on the text now. A work stage started by the Objective label applied after its plan's record asks nothing and makes the plan again, a kept edit or not: the label is a person's own word. Where it is asked: a work or review stage asks at its start, once its harness, account and credential checks pass and before anything acts on the text, on the stage's decider (the gateway with a key, else its own harness on a credential read of its own, masked in what the stage saves: a federated key comes with no expiry, so the passes read theirs as they start, never one minted before setup and install); the merge pass, which has no stage harness, asks the gateway when its process holds the key (local mode's `~/.config/pendulum/ai-gateway-key`) and the route allows, and says a kept edit on a progress comment of its own; else, when another process may judge it (a stage's harness on `auto`, or on Actions a stage job's key on `gateway`), it puts the review label back on so the review stage's start judges it (on Actions the dispatcher's job holds no key, so it always does), and otherwise (`gateway` with no key, locally) Blocks; a session's `pendulum issue` and `post-review` ask the gateway only and write no verdict, and `deliver` writes the plan with the plan's own record when the edit was kept. Otherwise a changed text Blocks (cause `work`: an edit is a person's action) and the PR becomes a draft, unless the stage is a work stage and the label was applied again after the recorded time: then the plan is made again from the new text, the earlier plan comment is not handed to the harness, and the branch and PR carry over. A plan comment whose record cannot be read (none, one that does not parse, another App's) is decided on GitHub's edit times instead: a body edit (`lastEditedAt`) or a title change after the comment was posted is a change, and the label applied after that edit plans again. There a save that changed nothing still counts as an edit, since only a record's hash can tell; a plan comment without a record gets one at the next work stage. With no plan comment, a stage uses the text as it is, and a stage that knows no record never erases one. Comments are never edits. Pendulum's own login must be known for any of this; when it cannot be read, the stage stops. On a session's route, `pendulum issue` writes `plan.md` beside `issue.md` only when the plan was made from the current text (or the edit check read the edit as wording only), `deliver` delivers nothing when the issue changed after `pendulum issue` gave it to the session and records the text it gave with the plan, and `post-review` posts nothing on an Objective edited since its plan. +Edits. The plan comment records the Objective text its plan was made from, on its marker line, written only by Pendulum: the SHA-256 of the title and body (line ends as LF, trailing whitespace dropped, so a save that changes nothing else is no edit), the time of the latest trusted activation, read before the text, when a work stage last started from that text, the text itself (title, body and harness, model and host labels: an edit's before) and the edit check's verdict for each later text, by its hash, as GitHub's 65,536-character limit leaves room for them, counted in UTF-8 bytes: the verdicts go first (they are asked again), the text only when it does not fit alone. In the record, `<` and `>` are JSON escapes, so no text in it closes the comment. A write of the plan comment keeps the verdicts another process wrote on it for the same text since this one read it. The plan comment read is the newest written by Pendulum's own login or a person who can push (local mode writes as its developer). No other App's comment counts, `github-actions[bot]` included: it never stands in for that comment. Only when there is none, the earliest App comment carrying the marker (Pendulum's App, read from a local process) counts for its time, so the stage decides on edit times (below) instead of on no plan; its text and any record in it are never read. After the trust check, each work stage and review job compares the text it read with that record before anything is set up for it, and the merge pass compares the text as it stands before it merges or enqueues, and while the PR waits in the merge queue (it is taken out of it). The same text goes on. A changed text is first judged by the edit check (`lib/edit-check.mjs`), a decision call asked once per distinct new text, its verdict written on the record: given the title and body before and after, does the edit change what has to be built? `wording` (typos, formatting, rewording only) at the confidence floor (Red-check triage, below) keeps the plan and the code: the stage goes on as on the same text, says so in one line on its progress comment (the verdict, the decider that gave it and its confidence), and the record still names the text the plan was made from, so the next edit is judged against that text too, and a work pass paused in local mode is held to that text (`lib/continue.mjs`) and continues. Any other answer, or none, is the rule below. A harness, model or host label added, removed or changed is a changed requirement as it stands, never asked about. The edit check is asked only on text that passed the trust check (its author, last editor and latest title renamer). A record without its text (one written before the record kept it, or one too long for the comment), a text whose hash is not the record's, a text too long to show the decider whole, or no decider (`decision_route` off, or `gateway` with no key) is never judged; with `decision_route` off a verdict the record keeps is not used either, and any verdict is used only after the same checks on the text now. A trusted activation after a plan's record requests a new plan. The work stage makes it even if the edit check kept the prior plan. Where it is asked: a work or review stage asks at its start, once its harness, account and credential checks pass and before anything acts on the text, on the stage's decider (the gateway with a key, else its own harness on a credential read of its own, masked in what the stage saves: a federated key comes with no expiry, so the passes read theirs as they start, never one minted before setup and install); the merge pass, which has no stage harness, asks the gateway when its process holds the key (local mode's `~/.config/pendulum/ai-gateway-key`) and the route allows, and says a kept edit on a progress comment of its own; else, when another process may judge it (a stage's harness on `auto`, or on Actions a stage job's key on `gateway`), it puts the review label back on so the review stage's start judges it (on Actions the dispatcher's job holds no key, so it always does), and otherwise (`gateway` with no key, locally) Blocks; a session's `pendulum issue` and `post-review` ask the gateway only and write no verdict, and `deliver` writes the plan with the plan's own record when the edit was kept. Otherwise a changed text Blocks (cause `work`: an edit is a person's action) and the PR becomes a draft, unless the stage is a work stage and the Objective was activated again after the recorded time: then the plan is made again from the new text, the earlier plan comment is not handed to the harness, and the branch and PR carry over. A plan comment whose record cannot be read (none, one that does not parse, another App's) is decided on GitHub's edit times instead: a body edit (`lastEditedAt`) or a title change after the comment was posted is a change, and a trusted activation after the edit plans again. There a save that changed nothing still counts as an edit, since only a record's hash can tell; a plan comment without a record gets one at the next work stage. With no plan comment, a stage uses the text as it is, and a stage that knows no record never erases one. Comments are never edits. Pendulum's own login must be known for any of this; when it cannot be read, the stage stops. On a session's route, `pendulum issue` writes `plan.md` beside `issue.md` only when the plan was made from the current text (or the edit check read the edit as wording only), `deliver` delivers nothing when the issue changed after `pendulum issue` gave it to the session and records the text it gave with the plan, and `post-review` posts nothing on an Objective edited since its plan. Split Objectives. A part's exit record lists the checklist items left; its PR says `Refs #N` instead of `Closes #N`, and Pendulum records the part on the issue. When it merges and the issue stays open, the dispatcher deletes `pendulum/N` and queues the Objective again; the next part starts from the default branch with the plan and the merged parts' PRs in `$PENDULUM_IN`. One PR is open at a time, and an Objective that needs more than six parts (`max_parts`) Blocks; the cap bounds how many PRs, not the spend (each part's work and review jobs, its rebases, re-reviews and resumed stages are each capped by `max_usd`), and the task card names it, so a worker whose plan needs more parts Blocks before it builds any. @@ -235,15 +235,15 @@ Pendulum merges on its own (`auto_merge`, on by default); the gate is CI green o The reviewer is one model call per PR on the top model, and one more for each chunk of commits written after it (below), on a head whose validation is green or still running. A head without the validated marker (handed off by the worker, pushed or marked ready by a person) gets Pendulum's validation in the review stage. With required checks and a reviewer to run, the reviewer starts at the first reading that shows a check run on the head (CI has started) and no required check red, once the PR's mergeable state reads no conflict, and the wait goes on beside it: a head that conflicts, whose checks never start, or whose reading already shows a required check red gets no reviewer pass yet, but its fix passes first, as does every head when the reviewer does not run or validation is the commands alone, and a red that stays red Blocks before any review. A head handed off from the local route is not given its commands again on that first pass. A red the checks show while the reviewer runs, or after it (after triage's rerun and the base-failure check, as any red), gets no fix pass of its own: once the reviewer is done, the answer pass takes it with the reviewer's comments, its failures in the prompt and their whole logs in `$PENDULUM_IN/checks/`, and runs even when the review has no comment. A conflict, a check that never starts or a base failure ends the stage as before, ending a reviewer call still running, and its review is not posted, so the next review stage reviews the head it works on. The validated marker goes on the head the checks were green on; when the PR's head moved meanwhile (a person's push), the stage posts nothing and puts the review label back on for the new head. The reviewer's rerun and the foundation pass finish the review that started. The progress comment shows the overlap: the reviewer's line ends `beside the required checks on `, the pass's own lines meanwhile start `during the reviewer:`, and the checks' end is `required checks on green|red|settled while the reviewer runs`, or, when they outlast the reviewer, `waiting for required checks on after the reviewer`; the scorecard counts each minute once, the overlap as review beside CI (bench/README.md). It gets the Objective text, the diff and the PR body, and it posts review comments tied to lines, each naming the acceptance entry or repository rule it concerns, with assumptions that change behaviour flagged explicitly. It also judges every acceptance entry, met or not, with the line that shows it: Pendulum lists the issue's entries in the prompt, puts the judgments in the review body, names any entry left unjudged, and turns an entry judged not met into a comment the worker must answer. On a split part that leaves work for the next, the prompt says it is part N and not the last: an entry the PR body assigns to a later part is judged deferred and gets no comment, while one the body claims and the diff does not deliver is still a finding. The last part and a one-PR Objective are judged against every entry. Reason: otherwise every earlier part re-raises the entries later parts deliver, and the worker rebuts each one. An entry a maintainer's recorded decision assigns outside the PR (to the owner after the merge, to another issue) is judged not met with that decision's key, and gets no comment: Pendulum keeps the judgment only when the key is exactly one of the stage's trusted decisions (authors with write access), lists the entry in the review body as assigned by that decision, with its author and link, and never counts it met; any other key is a plain not met. Before each reviewer call Pendulum writes `$PENDULUM_IN/decisions.md` with every trusted decision, uncut and under its key, so the decisions the prompt cuts for length are there to read. An entry whose finding from an earlier review is still open on the PR gets no second comment, unless the last stage's finding check got no verdict on that finding's answer: the stage judges it again after the review goes up (below) and may resolve it, so the entry gets its comment in the review (two open threads for one entry when the check then leaves that finding open). A review with no line comment beside such an entry, or one a decision assigns, has a placeholder that says there are no new line findings and points to the body. Reason: a decision the reviewer cannot read or cannot cite turns the entry into a finding every round, which no change on the branch can answer. A call that fails (a crash, a non-zero exit, a cap) or an answer that holds no JSON or judges none of the entries is a missed pass: it reruns once in a fresh session on every harness, on the fallback reviewer where the harness has one. A provider's refusal is not rerun, a subscription's usage limit included (below): the fallback model draws on the same subscription. When neither call produced a review, nothing is posted and the Objective Blocks with how each call ended: no placeholder stands in for a review that did not happen, and Pendulum never merges past the review. A rerun that answered but judged none of the entries is posted, and its placeholder says it is not a clean pass. Entries left unjudged are recorded on the review, not enforced: they do not hold the merge. It has no verdict and no refuse path: a reviewer that can stop a run turns every false positive into a hold. An Objective labelled `pendulum:foundation` (trusted as the harness and model labels are, and outside the plan's record, since it changes only the review) gets a second call after that one, the foundation pass: it checks each shared contract the diff adds or changes against its callers in the repository, and shared test fixtures against isolation, and returns line-tied comments only, which go up in the same review. It runs within the job's `max_usd` like any call, reruns once when it misses, and when it cannot run or never answers nothing is posted and the stage Blocks, as for the first pass. The review that includes it carries a second marker (``): a PR reviewed before the label was added gets the foundation pass alone at its next review stage, and a rebased PR keeps its review only when that marker is there. Reason: a defect in a contract later work builds on (a mapping that folds new error codes into an old one, a fixture that writes the developer's real state) passes a review of the diff alone, and every later Objective inherits it. The worker gets the comments once and addresses or rebuts each; Pendulum pushes, posts the replies, and validation runs again; rebutted findings stay visible on the merged PR. Each finding the answer pass replied to (Pendulum's reviewer's, a named reviewer's, code scanning's) then goes to the finding check (`lib/finding-check.mjs`), before another answer round is spent on it. A reply that says the finding is fixed and names a test that fails without the fix (replies.json's `fixed` and `test`: one of the validation commands exactly as listed, a single simple command, and the arguments that run only that test, at least one of them no option; the answer pass is offered `test` only when there are validation commands) has that test run through the stage's own validation path (`runValidation`: its sandbox and env), each argument shell-quoted, in the checkout itself: first on the PR's head, then, when the commit the finding was raised on (else the head the stage's review covers) is known green (Pendulum's validated marker on it, and no red the stage held there: a command that runs more than the test fails on a red commit for any red it had), on that commit's tree with the head's copy of each argument that names a file put back, after which the checkout is reset to the head and its HEAD and tracked files checked. Each run gets the stage's time left less a reserve for the exit, and none starts with under a minute of it. Failing without the fix and passing with it resolves the finding; failing on the head leaves it open (`test failed`) with no decision call. A test that passes both ways is no evidence, and one that cannot be run so is not checkable (a command that is no validation command or not one simple command, no test argument, a commit not known green, a dependency manifest or lockfile changed since that commit, a checkout not clean at the head, a run that timed out or changed tracked files, too little time): either reply goes to the decision model, its note kept for the Block. Only the named test is run: a reproduction written in a reply's prose is never run. For every other reply the decision model is asked whether the answer resolves it, `fixed` (the change shows it), `rebutted` (the reply names an acceptance entry or repository rule that permits the code), `decided` (a maintainer's recorded decision, not overruled by a later one, speaks to the very entry, rule, file or behaviour the finding concerns and settles it: it waives or changes what the finding asks, assigns that work outside the PR, such as to the owner after the merge, or permits the code; general approval such as "LGTM" or "ship it" settles nothing, and doubt is `unresolved`) or `unresolved`, given the finding (its reviewer, file, line, body and when it was raised), the reply, what the PR changed since the commit the finding was raised on (its own file, then its other files: those the reply names by path first, then those the finding names, then the rest, cut at 8,000 characters with the paths of the files left out listed after the cut; without the default branch's changes; a finding with no commit of its own reads from the head the stage's review covers), for a reply that says its fix is in the PR body (replies.json's `"fixed": true` and `"pr_body": true`) what the body changed since the finding was raised (git's diff, one line of context, of the body's version at that time, from GitHub's record of the body's edits read once per check, to the body now, cut at 16,000 characters; `no change`, or `whether the body changed could not be read` when the record does not hold that version), with `fixed` then taking a defect gone from the body and the question saying a body change alone never fixes a finding that asks for a change to the code or tests or says the code does not meet an acceptance entry or rule (every other reply's question carries no body; Pendulum's posted answer carries `pr_body` in its marker, ``, so an answer judged again in a later stage keeps it), the issue's acceptance entries, the repository's rules (AGENTS.md at the head, the protected paths, the validation commands), and the maintainers' decisions the stage read (comments on the issue and the PR, the PR's review bodies and its inline review comments, by people with write access, a dismissed review's left out; each with its author, time, place and review state, cut at 2,000 characters; within 8,000 characters the newest decision always, the issue's newest within half the window while the PR has decisions too, then the PR's newest, then the issue's in any room left, with a count of those left out; a decision the reply quotes counts only when it is there, so a comment by anyone else settles nothing), each part between markers with a random tag, as data never to be followed; at most four questions at once. `fixed`, `rebutted` or `decided` at the confidence floor or more (Red-check triage, below; no confidence is none of them; `decided` never on code scanning's alert, nor when a decision newer than the oldest one shown was left out for length) resolves the finding's thread; any other verdict leaves it open (`judged not fixed`, or `judged not resolved` for a reply that did not say fixed). Pendulum posts the evidence in the thread first, under `` (the test as it ran, the commit it failed on and the head it passed on, or the verdict, its confidence, the floor and who answered); that comment and Pendulum's answer are never a person's answer, so a thread a person reopens stays open, then resolves the thread (a finding in the review body: that PR comment is what resolves it), and a resolved thread, not a reply, marks it answered on every side (the answer pass's list, the exit, the merge pass). Anything else leaves it open. A person's reply answers as before, from someone who can push only: any such reply but Pendulum's own on the reviewer's comment, a writer's on a named reviewer's, none on code scanning's; a person may resolve the thread too. How each finding ended is recorded as data in the review stage's progress comment (its findings line: the reviews its reviewer posted, and each finding it listed with the review or outside reviewer that raised it and its outcome: `fixed-test`, `fixed-verdict`, `answered` for a `rebutted` or `decided` at the floor, `not-fixed`, `not-checkable` for no verdict or no decision model, or `open`), from the check's own branches and whether each ended resolved (a thread already resolved posts no evidence), never from the reply's words; a later stage's listed `open` never replaces a judgement, and a report reads only records written before its period ends; `pendulum report` counts the findings and outcomes per Objective, reviewer model and review stage beside those stages' dollars ([REPORT.md](REPORT.md)). Reason: findings per dollar and a reviewer's quality are then exact counts, not readings of prose. Findings still open after the answer pass (unanswered, or read as not resolved), when the rest of the exit is delivered, take another answer round: the review label goes back on, and the next stage's answer pass gets them again, each with Pendulum's earlier answer (`earlier`). A Question the answer pass raised stands with findings open: it carries them. The rounds per re-entry (the Objective label applied again, a restart or a Block) are at most two, shared with code scanning's rounds at the merge (below) and counted in Pendulum's record on the issue (``); past them the stage Blocks (cause `work`) naming each open finding, with what the check found on it (`test failed`, `judged not fixed` or `judged not resolved`, after `not evidence` or `not checkable` for a named test that proved nothing), and how to clear it: a fix on the branch, a reply by someone who can push or a resolved thread, or for a finding in the review body that resolved marker by someone who can push. An answer the gateway gave no verdict on (a failed call, a refused key, an answer outside the choices; once the key is refused no further question is asked in the stage) costs no answer round: it goes to no worker pass, the review label goes back on, and the next stage judges it again first (when that stage was started only for this, an answer it then reads as not resolved waits for the answer round its exit takes); the second stage in a row without a verdict Blocks naming the decider's error code (cause `setup` for a refused key, `provider-quota` for a rate limit or spent credits, else `outage`). With no decider (`decision_route` off, or `gateway` with no key) the decision model's part is off: a reply answers its finding as before unless a test it names proves the fix or fails on the head, the progress comment says `finding check: off ()` once per stage, and doctor's `finding check` line warns. The reviewer reads each chunk of work once. The answer pass's and the fix passes' commits are the review's answer and get no review of their own when they do only what the review's findings and the failing checks asked. The answer gate decides it: Pendulum asks the decision model red-check triage uses (the same key, `triage_model`, below) one question, `only_asked` or `more_than_asked`, giving it the diff they wrote since the head the review read, with the default branch's changes left out (the replay below), then each finding the answer pass answered (path, line, body) and the failure lines and output's end of each red the fix passes and the answer pass were given, at most 32 KiB in one question (`ANSWER_INPUT_BYTES`). A diff too large for one question is asked about in parts, each with the findings and failures and each within that size: whole files packed in order, and a file too large alone split into its hunks, packed in order the same way, each part with the file's header; four parts at a time, none started once one is held. Only every part covered covers them, and the first part held is named (`part of … ()`); a single hunk too large for a question is not judged, named in the hold, and no part is asked, even with no decider. Before each question, the first included, the stage's `max_usd` (in known dollars: a price still settling counts nothing) and its wall clock are read: once either is reached, that part and every later one are not judged, each named in the hold, and never covered. The question says a failing check asks only that it pass with the smallest change, so new behaviour or a feature is more than asked even when a check's output mentions it. The diff, the findings and the failures go as data (fenced, or JSON strings), with no worker secret in them. Pendulum records the head they leave in its own comment on the PR (``, edited in place), and the later of that record and its last review's `commit_id` is the head the review covers. Only `only_asked` at the confidence floor (Red-check triage, below) covers them. Anything else holds the PR: a lower or missing confidence, `more_than_asked`, a call that fails, times out or answers outside the two choices, no key, a hunk too large for a question, a diff over 16 MiB (not read whole), a file git diffs as binary (its numstat `-`, or `Binary files … differ`: a text file with one NUL byte is one, and the model would see none of it; no question is asked), or a diff that cannot be told apart. Then the record stays on the head the review read, marked as an answer's (`:answer` after the sha), the review label goes back on, and the next review stage's pass reads those commits. That pass's own answer is gated too: held again, the stage Blocks (cause `work`) naming why, the record staying on the head that pass read, and a person reviews those commits, so the gate never loops. The gate's answer goes to the job log (`answer gate (): → …`, with `(in parts)` after the confidence for a diff asked about in parts). The review goes up on the head the reviewer read (its `commit_id`), which is the head Pendulum's checkout was on when the reviewer started; when GitHub's head is no longer Pendulum's by then (someone else pushed), nothing is posted and the review label goes back on for the new head. A pass on new commits that finds nothing leaves the earlier reviews' open findings to the answer pass. A review stage whose head is that head, or only a rebase of it (the covered head's own change, replayed with `git merge-tree` onto the head's merge base with the default branch, gives exactly the head's tree: a clean rebase, GitHub's update-branch merge, Pendulum's merge of a default branch), runs no reviewer and goes on to validation and the merge. Commits written after it (the work stage's answer to a Question, a maintainer's push, a resolved conflict) get a reviewer pass before the merge, on the diff from that replay to the head, so neither the reviewed code nor the default branch's changes are in it; when the replay conflicts, the pass gets the whole PR. The prompt and the posted review name the head it follows on; the pass judges every acceptance entry as a first pass does, and a foundation Objective's foundation pass runs on the same diff. An answer pass that applied maintainers' decisions (a Question's answer, a comment no pass had read) in new commits does not merge: the stage covers the head before it (the head the review read, marked as an answer's, when the answer gate holds what the stage wrote before it), puts the review label back on, and the next review stage reviews those commits. Reason: the one-pass rule keeps the same code from being reviewed twice, and code written after the review was never reviewed. -A repository may also name third-party reviewers, reviewer Apps outside Pendulum, by login (`third_party_reviewers`, such as `greptile-apps[bot]`; `lib/third-party-review.mjs`). Their review is part of the PR's review. After Pendulum's reviewer posts, the review stage reads the PR's reviews once for each named reviewer's submitted review whose `commit_id` is the head Pendulum's reviewer read. While one is missing, the stage does not wait in place: it records the wait on the PR (a comment, marker ``, counted only when Pendulum or someone who can push wrote it, since a local loop writes as its developer; the bound the dispatcher, `serve` and `run` wake the review at is its `minutes`, the `third_party_wait_minutes` setting of the stage that wrote it (20 by default, taken as at most 24 hours whatever the record says), from GitHub's creation time of that comment; the review stage that resumes judges the wait by its own setting), takes the `pendulum:review` label off, moves the Objective to In review when it is not there (a Question a person answered by marking the PR ready still carries `pendulum:question`) and ends with exit `waiting`, holding no local slot, runner or sandbox. The dispatcher's tick, on every route (the Action's, the sandbox's, `serve`'s), reads that record from the PR comments it already reads for send-backs. While the bound is ahead and the review is missing, it leaves the PR as it is: no merge pass, no branch update, no send-back; when it cannot read the PR's comments and third-party reviewers are named, it leaves the PR alone that tick too. Once that review of the head exists, or the bound has passed, or the PR's head is no longer the one the record names (a maintainer's commit, GitHub's update-branch), it puts `pendulum:review` back on, which starts the review stage on that route as any review label does. The reviews are read at most once a tick, and in `serve` at most once a minute per PR. An App's review submitted on a Pendulum PR that is not Pendulum's own ticks the dispatcher (`pull_request_review`, its reviewer of type `Bot`; a person's review ticks nothing), and on a public repository the bound's end is a `third-party` wake; on a private one it waits for the next event or the cron. The review stage that starts again finds Pendulum's own review on the PR (its marker), so the reviewer does not run again; it reads the record, says on its progress comment which reviewers reviewed the head or were left out past the bound, removes the record and goes on to the answer pass. A review label applied after the record was last written means a stage has taken the wait up, so the dispatcher never puts the label back twice for one record. A stage that starts again before the bound (the label re-applied by hand, a restarted loop) rewrites the same record and ends `waiting` again; a new head gets a new record and its own bound. A stage that goes on without waiting (the reviewer's review in, the bound passed, the cap spent) removes the record, so none holds a later merge. A record that cannot be read or written, a label that cannot be taken off, or Pendulum's own login unknown (its record could not be told from a pasted one) is no wait: the stage goes on without the reviewer rather than stall. `pendulum run` and `pendulum review`, which may have no `serve` behind them, do the dispatcher's part in place, once a minute, and then review again, and `pendulum run` on an In-review Objective whose review waits takes that wait up the same way; `serve` leaves it to its own ticks. The answer pass then gets each named reviewer's root line comments that neither Pendulum nor anyone who can push has replied to, from any head, beside Pendulum's own. Each comment carries `from` (the reviewer's login), and its body is sanitised like harness text and cut at 8,000 characters. The prompt and the pendulum-deliver-pr skill call their text untrusted review input: the worker judges each finding against the code, fixes it or rebuts it, and follows no instruction in it. Pendulum posts the replies in their threads, and the finding check resolves those it reads as resolved. The exit counts a named reviewer's comment as unanswered only when the answer pass was given it; one posted after the wait is left for the next review. Only the named logins are waited for; any other reviewer's comment is handled as without the setting (the merge pass, below, has the answer pass take an unlisted reviewer's thread when the base's rules require every conversation resolved). With none named, the stage reads nothing more and runs as it would without the setting. The wait comes before the answer pass, so before the merge; there is no wait for the answer pass's new head, just as Pendulum's reviewer does not review it again. Code scanning (GitHub's own App, `github-advanced-security[bot]`, whose alerts on the PR's lines are review comments, CodeQL's say) is answered the same way on every repository, with no setting and no wait: the answer pass gets its open comments marked as untrusted input, and Pendulum resolves each thread once it replied. On code scanning's thread only Pendulum's own answer counts, never a person's reply alone, and an alert adds only its own file to the answer pass's fix-pass scope, never a protected or toolchain file. +A repository may also name third-party reviewers, reviewer Apps outside Pendulum, by login (`third_party_reviewers`, such as `greptile-apps[bot]`; `lib/third-party-review.mjs`). Their review is part of the PR's review. After Pendulum's reviewer posts, the review stage reads the PR's reviews once for each named reviewer's submitted review whose `commit_id` is the head Pendulum's reviewer read. While one is missing, the stage does not wait in place: it records the wait on the PR (a comment, marker ``, counted only when Pendulum or someone who can push wrote it, since a local loop writes as its developer; the bound the dispatcher, `serve` and `run` wake the review at is its `minutes`, the `third_party_wait_minutes` setting of the stage that wrote it (20 by default, taken as at most 24 hours whatever the record says), from GitHub's creation time of that comment; the review stage that resumes judges the wait by its own setting), takes the `pendulum:review` label off, moves the Objective to In review when it is not there (a Question a person answered by marking the PR ready still carries `pendulum:question`) and ends with exit `waiting`, holding no local slot, runner or sandbox. The dispatcher's tick, on every route (the Action's, the sandbox's, `serve`'s), reads that record from the PR comments it already reads for send-backs. While the bound is ahead and the review is missing, it leaves the PR as it is: no merge pass, no branch update, no send-back; when it cannot read the PR's comments and third-party reviewers are named, it leaves the PR alone that tick too. Once that review of the head exists, or the bound has passed, or the PR's head is no longer the one the record names (a maintainer's commit, GitHub's update-branch), it puts `pendulum:review` back on, which starts the review stage on that route as any review label does. The reviews are read at most once a tick, and in `serve` at most once a minute per PR. An App's review submitted on a Pendulum PR that is not Pendulum's own ticks the dispatcher (`pull_request_review`, its reviewer of type `Bot`; a person's review ticks nothing), and on a public repository the bound's end is a `third-party` wake; on a private one it waits for the next event or the cron. The review stage that starts again finds Pendulum's own review on the PR (its marker), so the reviewer does not run again; it reads the record, says on its progress comment which reviewers reviewed the head or were left out past the bound, removes the record and goes on to the answer pass. A review label applied after the record was last written means a stage has taken the wait up, so the dispatcher never puts the label back twice for one record. A stage that starts again before the bound (Draft removed by hand, a restarted loop) rewrites the same record and ends `waiting` again; a new head gets a new record and its own bound. A stage that goes on without waiting (the reviewer's review in, the bound passed, the cap spent) removes the record, so none holds a later merge. A record that cannot be read or written, a label that cannot be taken off, or Pendulum's own login unknown (its record could not be told from a pasted one) is no wait: the stage goes on without the reviewer rather than stall. `pendulum run` and `pendulum review`, which may have no `serve` behind them, do the dispatcher's part in place, once a minute, and then review again, and `pendulum run` on an In-review Objective whose review waits takes that wait up the same way; `serve` leaves it to its own ticks. The answer pass then gets each named reviewer's root line comments that neither Pendulum nor anyone who can push has replied to, from any head, beside Pendulum's own. Each comment carries `from` (the reviewer's login), and its body is sanitised like harness text and cut at 8,000 characters. The prompt and the pendulum-deliver-pr skill call their text untrusted review input: the worker judges each finding against the code, fixes it or rebuts it, and follows no instruction in it. Pendulum posts the replies in their threads, and the finding check resolves those it reads as resolved. The exit counts a named reviewer's comment as unanswered only when the answer pass was given it; one posted after the wait is left for the next review. Only the named logins are waited for; any other reviewer's comment is handled as without the setting (the merge pass, below, has the answer pass take an unlisted reviewer's thread when the base's rules require every conversation resolved). With none named, the stage reads nothing more and runs as it would without the setting. The wait comes before the answer pass, so before the merge; there is no wait for the answer pass's new head, just as Pendulum's reviewer does not review it again. Code scanning (GitHub's own App, `github-advanced-security[bot]`, whose alerts on the PR's lines are review comments, CodeQL's say) is answered the same way on every repository, with no setting and no wait: the answer pass gets its open comments marked as untrusted input, and Pendulum resolves each thread once it replied. On code scanning's thread only Pendulum's own answer counts, never a person's reply alone, and an alert adds only its own file to the answer pass's fix-pass scope, never a protected or toolchain file. Pendulum's push and merge. The harness pushes nothing. Pendulum takes the branch as a git bundle the agent writes to a pipe, indexes its pack into a mirror only Pendulum can write (a mkdtemp directory under Pendulum's own 700 temp directory) with `git index-pack --strict`, so every object is fsck-checked whatever the git version, and checks it there: the paths changed since the stage started (GitHub's head before any harness ran), Git LFS pointers, the local media cap, and each LFS object's bytes against its pointer. It then pushes with an explicit lease on the head it last saw, to `refs/heads/pendulum/` only, and reads GitHub's head back. Before a push, when the default branch on GitHub changed a file under `.github/workflows/` since the branch's base, Pendulum merges it into the branch in the mirror (its own merge commit, from `git merge-tree`) and the checkout fast-forwards to it (one that cannot, with uncommitted edits in the way, keeps the branch on that merge: the next push merges the checkout's new commits onto it, so the branch only moves forward): GitHub refuses a token without the Workflows permission, the App's or the local one, a branch whose workflow file is a version no branch has any more, which is what a run cut before such a change carries. A new branch that conflicts with that merge is not pushed; the harness resolves the conflict once, as a send-back's conflict pass does, and Pendulum pushes again. That pass answers like the work pass: a cap it reaches Blocks with that cap, and a death, or a rebase or merge it leaves in progress in the checkout, Blocks with nothing pushed. A push GitHub refuses for a workflow file Blocks with that cause, in Pendulum's words; any other refused push Blocks with git's status word and the exit code, and GitHub's own text goes to the job log only. A fetch, Git LFS upload or push of the mirror's that got no answer from the remote (a dropped connection, DNS, TLS, an HTTP 5xx, 408 or 429: anything but the remote's answer, which is the push's porcelain line for the ref, other than git's `[remote failure]`, or an HTTP 4xx refusal; `lib/outbox.mjs` gitTransport) is tried again up to four times within a minute and the stage's real end (its deadline plus the 15 minutes kept for the exit, so a timed-out stage's last push retries too); a push whose answer was lost but whose head GitHub now has counts as pushed, and is not sent again. A refusal (a ref line in git's porcelain, an HTTP 4xx) is never retried; one git reports with no status (a missing ref, a failed authentication) stands once those tries are spent. GitHub's head is read back up to five times over about 30 seconds, and at least three times. A refused or rejected push, or a head that is not the one checked, Blocks. Nothing is armed for later: the review job records the head it reviewed and validated as mergeable, and merges exactly that head (the merge endpoint's `sha`, or enqueue with `expectedHeadOid` on a merge queue) once its required checks are green, the review is done and no maintainer decision is unread, or the unread ones ask for nothing (the comment check: the decision model, given the issue, the PR and every unread writer comment whole with what it is, reads them as asking nothing at the 0.7 floor, and a fresh read after the call finds nothing new; a writer's review requesting changes always holds the merge; they are then recorded as read on a progress comment of the merge pass's own); otherwise the dispatcher's merge pass does it on a later tick. Just before the merge, on every route, the merge pass reads the PR's review threads: it resolves the ones Pendulum handles (its reviewer's, the named reviewers' and code scanning's, and under a rule below the unlisted reviewers') that a person answered; a code scanning comment still open (posted after the answer pass, or answered and not resolved by the finding check) puts `pendulum:review` back on, so the answer pass takes it, within the answer rounds (above: at most two per re-entry, counted in ``), and past them Blocks (cause `work`) naming each open alert's file and line. When branch protection or an active ruleset on the base requires every conversation resolved, a named reviewer's open thread no person answered (posted after the answer pass, or answered and not resolved by the finding check) goes back the same way, and so does an unlisted reviewer's: one nobody named whose root comment is by someone who can push or by a GitHub App (a `[bot]` login, which can comment only through an installation on the repository). So under that rule every App installed with pull-request write on the repository or its organization, reviewing or not, can put text before the answer pass's model, always as untrusted data. The review stage reads the same rule on the PR's base (`lib/third-party-review.mjs` `unlistedRule`, read only when such a comment is on the PR) and takes the same threads, classified once by `github.mjs` `reviewThreads` for both passes (REST and GraphQL name some Apps differently: Copilot's reviewer is `Copilot` in one and `copilot-pull-request-reviewer[bot]` in the other). An App's comment goes to the answer pass beside the named reviewers', with `from` its author, sanitised and marked as untrusted review input, and a person's reply answers it as it does a named reviewer's. A writer's comment among the stage's kept decisions (its author's write access checked) is a maintainer's decision: the answer pass gets it with `writer` its author, its text once (under the decisions when they show it); one that is not (an author association of MEMBER or COLLABORATOR can be read-only) is untrusted input with `from`, as an App's is. Every such body is one JSON string in the prompt's list. Only the finding check's yes or a person resolving the thread settles a thread its opener's association counts as a writer's, never a reply. The finding check, the answer rounds and the thread's resolution are otherwise a named reviewer's. When a thread no answer pass takes is open too, the merge pass Blocks at once rather than spend a round. Under that rule any other unresolved thread (a stranger's; `github-actions[bot]`'s, which every workflow run in the repository posts as, one a stranger's comment or pull request starts included, so it stands for no installation and counts as a stranger; or an answered one Pendulum could not resolve) never reaches a model and Blocks (cause `work`) with a reason naming each thread's author, file and line. Without such a rule, no unlisted reviewer's thread is read for the answer pass or holds the merge. A merge GitHub refuses just after the pass resolved threads is tried once more after a moment. That is read from the threads and the rules, before the merge and again after a refusal, never from GitHub's words. Threads or rules that cannot be read leave the merge to GitHub's own rule. A merge or enqueue GitHub refuses because another pass already merged the PR, or queued it at the reviewed head, counts as done; that is read from the PR again, never from GitHub's words. The dispatcher's tick comes from events, never only from GitHub's cron: CI finishing on a Pendulum PR's head (the launch gate's merge tick on the sandbox route; the dispatcher's own `workflow_run` and `check_suite` triggers without one), a Pendulum PR merging, the queue dropping one (`pull_request` `dequeued`), and the queue watch. A PR the queue drops unmerged (its checks failed or timed out on the queue's commit) is enqueued once more, and the issue gets one line saying so with the queue's code and time; dropped again, the Objective Blocks with the queue's reason codes, read from the PR's timeline; when the queue's jobs ran and failed, the Block names the failed jobs of its newest failed run and each one's first failure line, with the cause and advice of what the review stage read the red drops as (below): GitHub's side is an `outage`, the default branch's own failure says to fix it there, a flake read each time says to steady that test, and anything else is the work's. A drop whose newest removal is a red run on the queue's commit (`failed_checks`) goes to the review stage first, once per drop: the merge pass records it on the issue (marker ``, its JSON record `{at, state, head, after, kind, sigs, tries, reads}`, `head` the PR head the drop was of) and puts `pendulum:review` back on; a record still `handed` is handed again on a later pass. Records count from Pendulum or anyone who can push, since a merge pass and a review stage of one Objective can run under different logins (`serve --all` beside the Action's dispatcher). The review stage takes the newest record when it is `handed`; one of another head than the PR's now is `superseded` and left. It reads the PR's `merge_group` runs of any status (the queue drops a PR at its first failed required job while the run's other jobs go on) created after the removal before the drop, or the drop count's bound, and at most six hours back (one page, newest first): the newest created by the drop is this drop's, never an earlier drop's. With no such run listed yet, or no failed check on it while it still runs, nothing is decided: the record stays `handed` and the next review stage reads it again; after two such stages (a failing check no Actions run carries) it is not known to be the PR's (`none`). On that run's commit it reads the failed check runs, and decides as for a red PR check: a required job GitHub never started (`not-started`), every failed job failing on GitHub's side (`infra`), triage's flaky verdict (`flaky`, asked as for a PR check, nothing rerun) and every failing job failing the same way on the default branch (`base`) are not the PR's change; a run or job logs it cannot read (`none`), and, with triage off, a failure that names no file or test the PR changes (`unclassified`), are not known to be. The record says so (`requeued`) and the merge enqueues it again or Blocks under the rule above. Anything else is the PR's own change, a deterministic failure in a job the PR's checks do not run (another OS, say) included: triage reads each job's log, not its name, and a failure that names a file or test the PR changes is never a flake. Its answer pass gets the failing jobs' lines and whole logs, marked as the queue's integrated commit, then validation runs on its new head and the merge enqueues it, whose drops count from that head. The record turns `fixed` only once that pass itself committed (the checkout's HEAD before and after it, not a merge Pendulum makes at the push) and the push went up; until then it stays `handed` with `tries` counted, so a stage that ends first (a crash, a stop, a pause, a cap, a wait for a third-party reviewer) leaves it to the next. The bound is progress, since the Objective's last re-entry (its label, `pendulum:restart` or a Block): each record keeps its failing jobs and their failure signatures, and a red after a fix pass is judged against the red that pass was handed, with every red fixed since the re-entry as the ones seen, as in the stage's own fix loop (`lib/fix-progress.mjs`, Exit: blocked, below); each record keeps its failing jobs (each one's signature and the digest of its folded failure lines with their counts) and their failure lines for the decision call, which is also given the fix pass's own commits; each stage try's end is recorded on the drop (`committed`, or `idle` when its pass ran, its harness started and returned, ok or not, and committed nothing; a try whose pass never ran, was stopped, or asked a Question records none and does not count, as the stage's own bounds cover those); no progress, or a try that ran and committed nothing, Blocks the stage (`blocked`), as the work's (an unmade judgement as Pendulum's or the outage's), naming the failure. There is no count of the queue's fix passes: while the decision model keeps reading each as closer to green, `daily_usd`, the owner's limit, is what stops them. Only drops after the latest of the review the merge rests on, the head's commit (GitHub keeps no push time for a branch push) and the issue's last re-entry or Block count, so a re-entry starts the count over even when its head keeps the earlier review. When GitHub never started the required job on a dropped entry's merge_group commit (no step, no runner: a billing lock, a spending limit), the Block says so as infrastructure, quoting GitHub's annotation, as validation does, rather than pointing at the checks. A queue commit on which CI never begins in 10 minutes (`queue_stall_minutes`) counts as a drop too, and so does one on which CI began but a required check makes no progress. Progress is read from the check's Actions job: its steps, each one starting and completing (a running job's log is not readable, so it is not used). The job is stalled when the step running now has run past max(3 × that step's normal duration, that duration + 15 minutes) (`step_stall_factor`, `step_stall_floor_minutes`), so never under 15 minutes (16 for a step that normally takes 1); the normal duration is the longest the same step of the same job took in the workflow's last 15 green runs on the default branch or in the merge queue, read with the job token once per dispatcher tick or queue watch, and only once a step has run 15 minutes. A step with no history, a running step GitHub gives no start time (counted from the check run's start), a check that is no Actions job, or a job Pendulum cannot read falls back to a time bound from the job's own start: the queue's check timeout (`check_response_timeout_minutes`, from the ruleset; setup's 60 when unread) less 10 minutes, at least half of it and at least 20 minutes, so 50 minutes at 60. A job queued or waiting for a runner, or with no steps yet, is never stalled. A required check not reported at all (an aggregate behind `needs:`) is judged by its upstream jobs' progress, and by the fallback from CI's first start when nothing runs there. The notice names the stuck step and its times, e.g. `` `Quality` / `Run scripts/ci/setup.sh` running 16 min, normally ~1 min ``. On the local route the Pendulum App has no Actions permission, so Pendulum reads no job steps or history there and the hung rule is the time fallback only, read once per merge pass. Pendulum takes the PR out and puts it back once, which restarts CI, and the second time Blocks naming the check. A removal for a hung step counts toward that only when the step really hung: its record holds each step judged hung (the required check's name, the job's id, the step's name and number, its times) and the queue's own deadline for that commit (the commit's time plus `check_response_timeout_minutes`, read once per merge pass with the hung bound; no deadline when it is unread, and such a removal always counts). When the drops would Block, Pendulum reads those jobs (with the job token; never on the local route), oldest removal first: a removal is cleared, and counts toward no try, when the judged step finished green and its job, the required check the queue waited on, concluded `success` by that deadline, so the queue would have taken that check's result. A job that failed later (a later step red), finished after the deadline, or was cancelled counts. One removal at most is cleared since the count's start; past that, every hung removal counts, so a step that is slow on every try still Blocks. While a judged job is still running before its deadline, or cannot be read then, the PR stays out of the queue and the decision waits, never past that deadline: Pendulum records that removal on the issue, and the run's end, a retry wake for a failed read, or the next tick brings the next pass. A person's removal and every other drop count as above. A removal Pendulum made reads its reason back from Pendulum's own requeue comment on the issue, which records it, since GitHub's timeline cannot say why Pendulum removed a PR. CI has begun once a check run or status named like a required check exists on it, or a check run or suite from the integration that provides the required checks (Actions when the ruleset names none), so an aggregate required job behind `needs:` that starts late is not a stall; another app's run, such as code scanning's, does not count. Any run from that integration counts, required or not (a `push` workflow that fires on the queue's branch, another `merge_group` workflow, a startup failure); one that never produces the required check is bounded by that rule and the drop handling. When the required checks cannot be read, any check run, any status, or any suite with a run counts. The queue-watch job, started by the dispatcher whenever its merge pass leaves a PR in the queue, reads the entry every 30 seconds until the PR leaves the queue, merged or dropped, or stalls there, and then ticks the dispatcher with its own `workflow_dispatch`; after 12 minutes it ticks anyway, and that run starts a new watch. Recovery from a drop never depends on the `dequeued` run: GitHub attributes that event to `github-merge-queue[bot]` and, under a strict approval policy for outside contributors, holds it for approval, while a `workflow_dispatch` by the job token is never held. The `dequeued` run stays a faster path where it runs; the merge pass reads the queue and the PR's timeline each time, so the two never enqueue a PR twice. Local mode's loop runs the merge pass every interval itself. A person's own removal from the queue is a hold, not a drop: Pendulum leaves the PR out until they enqueue it again, or it is reviewed again, gets a new head or re-enters. Doctor names an installed workflow rendered before these ticks (re-run `setup --apply workflow`), and, with a merge queue, warns when the repository's approval policy can hold the `dequeued` run (or cannot be read, which needs admin), saying recovery runs from the queue watch. The squash commit carries the PR's title and Pendulum's closing line, never the branch's commit messages; on a merge queue, setup sets the repository's squash default to the PR's title and body, and doctor checks it. A PR that fell behind gets GitHub's update-branch merge; that new head is accepted only when it is a merge of the recorded head and a default-branch commit, committed and signed by GitHub's web-flow key, with exactly the tree Pendulum's own `git merge-tree` of the two gives. Any other new head goes back to review. Pendulum's git runs only in its mirror, with hooks off and no global or system config; the agent's checkout gets the default branch, the branch and Pendulum's own clean rebase as bundles, and every git command there runs in the agent's sandbox. Only the commit Pendulum's rebase made, and only when it rebases the head Pendulum's review covers with nothing more, keeps the review and merges from the work stage; any other head (one the harness made: a resolved conflict, a fix; a rebase Pendulum then merged a workflow change into before pushing; a rebase of commits written after the review) goes back to the review stage, whose reviewer reads what it adds beyond a rebase of the covered head (above). GitHub failing for now is retried inside Pendulum's API client (`lib/github.mjs`), on every route: a 5xx, a 429 or secondary rate limit, or no answer at all (GitHub's primary rate limit spent is waited out to its reset in the stages and `serve`: below). Up to four tries per call, waiting what GitHub asks (`Retry-After`, a minute for a rate limit that names none) or 2, 4 and 8 seconds, each spread by up to 30% (a wait GitHub asked for only upward), at most 90 seconds in all and never past a deadline the caller passes; a longer ask is not waited out, and the caller sees the error. A caller that handles a rate limit itself (the dispatcher's blocked-by reads, the five-minute launch jobs) gets it at once. Only a call that means the same sent twice is retried: a read; a PUT, PATCH or DELETE that sets a state (not a merge or an update-branch); and adding labels to an issue or PR, which keeps the ones it has. A create (any other POST: a comment, a review, a PR, a repository label, a dispatch, a rerun; a GraphQL mutation) goes again only when it provably did not land: the connection was never made, or GitHub's rate limit turned it away (a 429, or a 403 with the rate-limit headers or message; a 5xx or 422 with those headers is no rate limit); or when a read finds it absent: the caller's, or for a comment on an issue or PR a read of the comments updated since just before the call, which finds one with the same body (line ends and trailing blanks aside) by Pendulum's login, or by anyone when the body carries a Pendulum marker (a notice is posted with the notice App's token), so a comment GitHub made before its 5xx is not posted twice; after a 502 or 504 that read waits ten seconds at least, and it keeps the call's deadline. Each retry is logged once with its cause and try number. A 5xx that is still GitHub's answer once the tries are spent (or a comment whose read for it fails) is an outage of GitHub, below: its code is the status (`HTTP 500`), and the stage ends on it, never on a crash Block. A refusal (a 4xx that is no rate limit) is not retried and stays the caller's error. -This machine's own network being down is not GitHub failing (`lib/network.mjs`). In a work or review stage, and in local mode's `serve`, a request that never left the machine (DNS, a refused or unreachable connect, a connect that timed out, or, behind a proxy, the proxy's 5xx to its CONNECT; read from Node's error code, never its message, except the proxy's status, which undici gives only in its one fixed tunnel message and which is read from that exact text) is no try: Pendulum probes that host, one request at a time after 5, 10, 20 and 30 seconds and then every minute, and sends the request again once the host gives any answer, a create included since it did nothing. Every other request to that host waits on the same probe rather than being sent, and the log has one line when the host is lost and one when it answers again; a host lost again within a minute of answering is the same outage, its first loss and its limit carried over and no new line logged unless it then stays down past a minute, when it gets one line then and one when it answers. Once a stage has stopped waiting, a request to a host it gave up on fails at once as that outage (its host, code and first loss), so the stage's end names it whichever call met it first. A Block that came from an outage ends on the outage instead, on any route, as below: a GitHub step of the exit (the split record, the review label, the mergeable record, the maintainers' comments read before a merge, the merge itself, the PR's first opening) that failed because its host did not answer, or because GitHub's core REST quota was spent (a spent GraphQL or search quota is no outage of a write). Any other Block stands, an outage or not: protected paths, a cap, validation, an exit record the harness wrote. While a host the stage gave up on still fails a probe, a harness pass cut off by its provider or the network (below) is no death and does not run again, and a run left with no exit record ends on the outage without the harness being asked, so its own account of a run the outage cut off never stands in for it; once the host answers again, such a pass runs again as above, and the harness is asked as ever. The App token's mint waits the same way. Any HTTP answer, a 5xx included, is the host answering and goes through the retries above, with no probe; a 5xx that outlasts them ends the stage on GitHub's outage at once, as one past the wait does (paused on the local route, where `serve` resumes it after a doubling wait for as long as GitHub's status page reports an incident: LOCAL.md; an `outage` Block elsewhere), and its reason names the request and says GitHub answered that status to every try since the first. A git fetch or push of the mirror that fails in transport while the remote's host does not answer a probe waits the same way, and its retry count starts again after. Pendulum's own git (the mirror's fetch and push, and its scratch repositories') reaches the network as its GitHub client does: through the proxy the stage process's own environment names when `NODE_USE_ENV_PROXY` is 1, else directly, and never through a proxy from git's own config or any other variable (`lib/network.mjs` `gitProxyEnv`). The settings are resolved as Node's fetch resolves them and given to git in the forms curl reads: `https_proxy` before `HTTPS_PROXY`, an https remote through the http proxy when no https one is set, and `NO_PROXY`'s entries (split on commas and white space, `*.` and a leading `.` dropped, a `host:port` entry kept only for the remote's port, `*` alone covering every host) rewritten as plain comma-separated hosts. An https remote goes through the proxy as a CONNECT tunnel carrying TLS, so its token reaches the proxy only encrypted. A proxy URL with a user and no password fails closed for git: git asks for the proxy's password, has no helper or prompt to answer it, and stops before connecting, while Node's fetch goes through the proxy with no proxy credentials. The repository's setup and install that fail while this machine's network is down run once more after it is back (`lib/checkout.mjs` `throughOutages`). Down is decided on exact facts only: an outage the stage recorded on any host while the step ran, GitHub's origin not answering a check on a fresh connection (no pooled socket stands in for it) that reaches the network as Pendulum's GitHub client does: through the proxy the stage process's own environment names when `NODE_USE_ENV_PROXY` is 1 (local mode's stages), else directly with its own DNS lookup, or one of the stage's own allowed hosts (the sandbox's built-in list, `PENDULUM_LOCAL_DOMAINS` or `allowed_domains`, and the Objective's approved `pendulum:host:` labels, as the route resolved them, those not GitHub's own first, lookups only) failing its lookup with `EAI_AGAIN`, as a resolver that still serves GitHub's names from its cache fails the rest. Nothing the step printed and nothing its checkout configures is ever probed or looked up, since the model edits both. The check connects only to GitHub's origin, the operator's own (`GITHUB_API_URL`, which may be a GitHub Enterprise Server on a private network); through a proxy, the proxy's failure to reach it (a tunnel it could not open, or its 502 for an http origin) is that origin unreached. The step waits for this machine's network, the same check, whichever host the outage was met on; such a failure is no try (an install's clean reinstall is not spent on it), a second failure while the network is down ends the stage on the outage, and so does the wait running out. A failure with the network up Blocks as before, its reason saying the network was up, that the step ran behind the local sandbox's proxy when it did, and that its first run met an outage when one did; it names no host. A harness pass whose model provider answered busy (`usage.mjs` `providerBusy`: HTTP 408, 425, 429 or a 5xx, 529 included, or with no status the AI Gateway's bare 5xx types `service_unavailable_error`, `overloaded_error` and `internal_server_error`; with no refusal type or code: a 5xx with an auth, permission, quota or billing type or code is that refusal; read from the same structured error as a refusal below, `providerError`) is no death and no network loss. Copilot's weekly and global rate limits (`user_weekly_rate_limited`, `user_global_rate_limited`) are not busy: they are usage limits with no reset reported, as its quota is. In a stage the pass waits 1, 2, 4… minutes doubling up to 30, or, when the error itself gave a time to go again and that is later, until that time: a 429's only, from its own fields (Claude Code's API error `api_error_params.rate_limit_info.resetsAt`; Copilot's `auto_mode_switch.requested` after the error with the same `errorCode`, its `retryAfterSeconds`), never an earlier or unrelated event. It then runs again from its own session (a reviewer's from its prompt) on what is left of its budget; the stage's time bounds it, not a count. A provider's time over an hour away goes through a usage limit's gate on a route with automatic account choice: another account free ends the stage as a usage limit, so the Objective moves there; else the stage's account is held until that time while it waits, so no other Objective starts on it. A wait that would end past the stage's in-place bound (fifteen minutes from the first busy answer on the local route, the work deadline elsewhere) or leave the pass under five minutes ends the stage: with the provider's time five minutes or more away, as a usage limit that resets then (its account held until that time, as any usage limit's is: paused locally, the holds record or a `provider-quota` Block elsewhere); else on the provider's host with the status as its code, as GitHub's 5xx does (paused locally, where `serve` resumes it on the same doubling; an `outage` Block elsewhere, which the dispatcher relaunches). A harness pass that fails (no cap, stop, provider refusal or busy answer) on a provider or network failure its harness reports with no status is no death: a server-error type (Claude Code's API error message `error: server_error`, which it gives a connection it could not make or a request that timed out), read from the same structured error (`providerError`), never the words. A pass whose harness reported a 4xx is no cut, whatever the network did while it ran: the provider answered and said why. Any other pass is judged on exact facts instead: one with no structured error at all (Codex prints a 5xx and a lost connection as prose only; a crash), and one whose structured error has no status and names no outage (a Copilot `session.error` with no `statusCode`, Claude Code's `unknown`). It is a cut when, between the pass's start and its end, this process met an outage of any kind on its provider's host (lost, or answering busy) or lost any host to this machine's network (a connect-level failure; a GitHub 5xx or another host's answer is none), or when its provider's API does not answer a probe now; otherwise it failed on its own. A cut pass waits, while its provider's API does not answer, as a request does; then, or at once when it answers, it runs again, from its own session when it has one (a reviewer's pass, and one with no session yet, as it was first run), on what is left of its budget and wall clock, at most twice, and its record carries every run's spend once. A stage's first steps (its token, the writers, the PR a review reads) end on an outage the same way as the rest. A stage waits in place up to fifteen minutes on the local route, where it then ends `paused` for `serve` to resume (LOCAL.md), and up to its work deadline on the Action and a cloud sandbox: still unreachable then, it stops waiting and Blocks with the External cause `outage`, naming the host, the error code and since when, if GitHub takes that one write, in a notice that mentions no one, since the dispatcher relaunches it. **A stage lost to a network failure on the Action and a cloud sandbox is relaunched** (`lib/relaunch.mjs`), being almost always transient. Two losses count. One is an `outage` Block that is the Objective's newest Blocked notice and was written after the Objective last became Running (GitHub's clock, from the issue's timeline, which the dispatcher already reads for every Blocked Objective and which carries the comments too); an older one never counts, so a later Block whose own notice did not land is not taken for it. The other is a stage that vanished with no exit because its runner or sandbox could not report: a Running Objective with no work job alive, or on the sandbox no stage within its lease, 15 minutes after its Running stint began. Those 15 minutes are for a job GitHub has not started yet: on the Action, a stint whose `work ()` job GitHub's jobs API shows completed after the stint began (cancelled mid-harness, or gone with no exit) is judged at once, on the tick its job's last step fires, provided the timeline still shows the stint Running, a fresh read of the issue shows it open, `pendulum:running` and in no other state, and no restart is waiting. A job still queued or running, none shown yet, a job read that failed, or only an earlier stint's job (completed before this stint began) waits, and the dispatcher's wake ticks at the 15 minutes' end (`job-grace`), so a job that ended with no tick of its own is judged then. A stint a relaunch began has its job in the relaunch's run alone (the run its record names, when that stint began with the first Running label after the record was written). A tick that lists a live work job whose final tick step has started arms a `retry` wake, since that step's tick may read the job before GitHub marks it ended. A work job that dies after a tick saw it alive, with no final tick of its own, is judged by the next tick after GitHub ends it (at the latest its `timeout-minutes`), with the cron behind it. The stint's job is read at most once a tick per Objective, and only for one with no work job alive; the tick reads each run's jobs once, and one runs listing serves every stint that began within 15 minutes of another. A vanished stage that left a sign the network was not what ended it is not relaunched (`endedNotLost`, read from the stint's `work ()` job as GitHub's jobs API gives it, its `conclusion` and `steps[]`, never a log): on the Action that job concluded `cancelled` or `timed_out` (a person, or the job's timeout: a stop, which keeps the vanished Block), or it failed before Pendulum ran, which is relaunched once (a checkout's or a token mint's 5xx, a runner not acquired, may pass), the step kept on the relaunch record, and Blocks with the cause `setup` naming the step when the relaunch's job fails at the same step (GitHub never started it: no step and no runner; or GitHub's `Set up job` failed; or a step failed before Pendulum's own work step, the step that `uses: clockgrove/pendulum@…` with `mode: work`, placed by reading the workflow file at the job's commit, one read only for a job that failed after its set-up: `Set up job` is step 1 and the job's steps follow in order, whatever they are named); on the sandbox its record says the stage ended. A job with no failed step of its own (its runner went away), whose Pendulum step failed with no exit written, or whose failed step cannot be placed because the workflow file cannot be read (the log says so) is lost. The dispatcher starts the work again as re-applying the label would: the Objective goes Running again, a new stint, and a work stage resumes its branch and PR (on a cloud sandbox, in the Objective's recorded sandbox), within `max_usd` like any stage. A relaunch spends like a pick: none starts while today's spend has reached `daily_usd` (it waits, unblocked, for the UTC day's turn, its `daily-cap` wake, or for a spend that can be read) or while `max_concurrent` is reached, and relaunches go before new picks. At most twice since a person last started the Objective (applied its label, started its draft, or restarted it), counted in a record Pendulum owns on the issue (marker ``, each try naming that start), so a dispatcher that restarts keeps the count and a person's start begins a new one. So one start can spend up to 3 × `max_usd` on stages lost this way before the person is mentioned. Past that it Blocks, whatever the caps, and the notice says how many relaunches were tried: cause `outage`, the person mentioned, when the stage ended on one; a vanished stage gets the vanished Block (`worker job vanished`, cause `pendulum`) with the count. A write the relaunch needs that fails (its record, its labels, the Block) is tried again on the next tick, never turned into a Block. An Objective whose timeline the dispatcher cannot read is left as it is until a read succeeds: a vanished one stays Running, as any Running Objective whose Running time is unread does, and an outage-Blocked one stays Blocked on its stage's notice, which mentions no one; there is no fallback Block for that. On the Action, the stint's `work ()` job is looked up in the run the relaunch record names (each relaunch records its dispatcher's run), else among the 10 newest runs created in the hour up to the stint's start; one not found is no sign either way, so the stage is relaunched. A stopped or draft Objective is never relaunched, nor is a restarting one (a vanished one gets the vanished Block, and its restart goes ahead). A Block whose newest notice is anything but a stage's `outage` notice is never relaunched. Every other command (the Action's dispatcher, doctor, setup, the launcher) keeps the client's bound above. +This machine's own network being down is not GitHub failing (`lib/network.mjs`). In a work or review stage, and in local mode's `serve`, a request that never left the machine (DNS, a refused or unreachable connect, a connect that timed out, or, behind a proxy, the proxy's 5xx to its CONNECT; read from Node's error code, never its message, except the proxy's status, which undici gives only in its one fixed tunnel message and which is read from that exact text) is no try: Pendulum probes that host, one request at a time after 5, 10, 20 and 30 seconds and then every minute, and sends the request again once the host gives any answer, a create included since it did nothing. Every other request to that host waits on the same probe rather than being sent, and the log has one line when the host is lost and one when it answers again; a host lost again within a minute of answering is the same outage, its first loss and its limit carried over and no new line logged unless it then stays down past a minute, when it gets one line then and one when it answers. Once a stage has stopped waiting, a request to a host it gave up on fails at once as that outage (its host, code and first loss), so the stage's end names it whichever call met it first. A Block that came from an outage ends on the outage instead, on any route, as below: a GitHub step of the exit (the split record, the review label, the mergeable record, the maintainers' comments read before a merge, the merge itself, the PR's first opening) that failed because its host did not answer, or because GitHub's core REST quota was spent (a spent GraphQL or search quota is no outage of a write). Any other Block stands, an outage or not: protected paths, a cap, validation, an exit record the harness wrote. While a host the stage gave up on still fails a probe, a harness pass cut off by its provider or the network (below) is no death and does not run again, and a run left with no exit record ends on the outage without the harness being asked, so its own account of a run the outage cut off never stands in for it; once the host answers again, such a pass runs again as above, and the harness is asked as ever. The App token's mint waits the same way. Any HTTP answer, a 5xx included, is the host answering and goes through the retries above, with no probe; a 5xx that outlasts them ends the stage on GitHub's outage at once, as one past the wait does (paused on the local route, where `serve` resumes it after a doubling wait for as long as GitHub's status page reports an incident: LOCAL.md; an `outage` Block elsewhere), and its reason names the request and says GitHub answered that status to every try since the first. A git fetch or push of the mirror that fails in transport while the remote's host does not answer a probe waits the same way, and its retry count starts again after. Pendulum's own git (the mirror's fetch and push, and its scratch repositories') reaches the network as its GitHub client does: through the proxy the stage process's own environment names when `NODE_USE_ENV_PROXY` is 1, else directly, and never through a proxy from git's own config or any other variable (`lib/network.mjs` `gitProxyEnv`). The settings are resolved as Node's fetch resolves them and given to git in the forms curl reads: `https_proxy` before `HTTPS_PROXY`, an https remote through the http proxy when no https one is set, and `NO_PROXY`'s entries (split on commas and white space, `*.` and a leading `.` dropped, a `host:port` entry kept only for the remote's port, `*` alone covering every host) rewritten as plain comma-separated hosts. An https remote goes through the proxy as a CONNECT tunnel carrying TLS, so its token reaches the proxy only encrypted. A proxy URL with a user and no password fails closed for git: git asks for the proxy's password, has no helper or prompt to answer it, and stops before connecting, while Node's fetch goes through the proxy with no proxy credentials. The repository's setup and install that fail while this machine's network is down run once more after it is back (`lib/checkout.mjs` `throughOutages`). Down is decided on exact facts only: an outage the stage recorded on any host while the step ran, GitHub's origin not answering a check on a fresh connection (no pooled socket stands in for it) that reaches the network as Pendulum's GitHub client does: through the proxy the stage process's own environment names when `NODE_USE_ENV_PROXY` is 1 (local mode's stages), else directly with its own DNS lookup, or one of the stage's own allowed hosts (the sandbox's built-in list, `PENDULUM_LOCAL_DOMAINS` or `allowed_domains`, and the Objective's approved `pendulum:host:` labels, as the route resolved them, those not GitHub's own first, lookups only) failing its lookup with `EAI_AGAIN`, as a resolver that still serves GitHub's names from its cache fails the rest. Nothing the step printed and nothing its checkout configures is ever probed or looked up, since the model edits both. The check connects only to GitHub's origin, the operator's own (`GITHUB_API_URL`, which may be a GitHub Enterprise Server on a private network); through a proxy, the proxy's failure to reach it (a tunnel it could not open, or its 502 for an http origin) is that origin unreached. The step waits for this machine's network, the same check, whichever host the outage was met on; such a failure is no try (an install's clean reinstall is not spent on it), a second failure while the network is down ends the stage on the outage, and so does the wait running out. A failure with the network up Blocks as before, its reason saying the network was up, that the step ran behind the local sandbox's proxy when it did, and that its first run met an outage when one did; it names no host. A harness pass whose model provider answered busy (`usage.mjs` `providerBusy`: HTTP 408, 425, 429 or a 5xx, 529 included, or with no status the AI Gateway's bare 5xx types `service_unavailable_error`, `overloaded_error` and `internal_server_error`; with no refusal type or code: a 5xx with an auth, permission, quota or billing type or code is that refusal; read from the same structured error as a refusal below, `providerError`) is no death and no network loss. Copilot's weekly and global rate limits (`user_weekly_rate_limited`, `user_global_rate_limited`) are not busy: they are usage limits with no reset reported, as its quota is. In a stage the pass waits 1, 2, 4… minutes doubling up to 30, or, when the error itself gave a time to go again and that is later, until that time: a 429's only, from its own fields (Claude Code's API error `api_error_params.rate_limit_info.resetsAt`; Copilot's `auto_mode_switch.requested` after the error with the same `errorCode`, its `retryAfterSeconds`), never an earlier or unrelated event. It then runs again from its own session (a reviewer's from its prompt) on what is left of its budget; the stage's time bounds it, not a count. A provider's time over an hour away goes through a usage limit's gate on a route with automatic account choice: another account free ends the stage as a usage limit, so the Objective moves there; else the stage's account is held until that time while it waits, so no other Objective starts on it. A wait that would end past the stage's in-place bound (fifteen minutes from the first busy answer on the local route, the work deadline elsewhere) or leave the pass under five minutes ends the stage: with the provider's time five minutes or more away, as a usage limit that resets then (its account held until that time, as any usage limit's is: paused locally, the holds record or a `provider-quota` Block elsewhere); else on the provider's host with the status as its code, as GitHub's 5xx does (paused locally, where `serve` resumes it on the same doubling; an `outage` Block elsewhere, which the dispatcher relaunches). A harness pass that fails (no cap, stop, provider refusal or busy answer) on a provider or network failure its harness reports with no status is no death: a server-error type (Claude Code's API error message `error: server_error`, which it gives a connection it could not make or a request that timed out), read from the same structured error (`providerError`), never the words. A pass whose harness reported a 4xx is no cut, whatever the network did while it ran: the provider answered and said why. Any other pass is judged on exact facts instead: one with no structured error at all (Codex prints a 5xx and a lost connection as prose only; a crash), and one whose structured error has no status and names no outage (a Copilot `session.error` with no `statusCode`, Claude Code's `unknown`). It is a cut when, between the pass's start and its end, this process met an outage of any kind on its provider's host (lost, or answering busy) or lost any host to this machine's network (a connect-level failure; a GitHub 5xx or another host's answer is none), or when its provider's API does not answer a probe now; otherwise it failed on its own. A cut pass waits, while its provider's API does not answer, as a request does; then, or at once when it answers, it runs again, from its own session when it has one (a reviewer's pass, and one with no session yet, as it was first run), on what is left of its budget and wall clock, at most twice, and its record carries every run's spend once. A stage's first steps (its token, the writers, the PR a review reads) end on an outage the same way as the rest. A stage waits in place up to fifteen minutes on the local route, where it then ends `paused` for `serve` to resume (LOCAL.md), and up to its work deadline on the Action and a cloud sandbox: still unreachable then, it stops waiting and Blocks with the External cause `outage`, naming the host, the error code and since when, if GitHub takes that one write, in a notice that mentions no one, since the dispatcher relaunches it. **A stage lost to a network failure on the Action and a cloud sandbox is relaunched** (`lib/relaunch.mjs`), being almost always transient. Two losses count. One is an `outage` Block that is the Objective's newest Blocked notice and was written after the Objective last became Running (GitHub's clock, from the issue's timeline, which the dispatcher already reads for every Blocked Objective and which carries the comments too); an older one never counts, so a later Block whose own notice did not land is not taken for it. The other is a stage that vanished with no exit because its runner or sandbox could not report: a Running Objective with no work job alive, or on the sandbox no stage within its lease, 15 minutes after its Running stint began. Those 15 minutes are for a job GitHub has not started yet: on the Action, a stint whose `work ()` job GitHub's jobs API shows completed after the stint began (cancelled mid-harness, or gone with no exit) is judged at once, on the tick its job's last step fires, provided the timeline still shows the stint Running, a fresh read of the issue shows it open, `pendulum:running` and in no other state, and no restart is waiting. A job still queued or running, none shown yet, a job read that failed, or only an earlier stint's job (completed before this stint began) waits, and the dispatcher's wake ticks at the 15 minutes' end (`job-grace`), so a job that ended with no tick of its own is judged then. A stint a relaunch began has its job in the relaunch's run alone (the run its record names, when that stint began with the first Running label after the record was written). A tick that lists a live work job whose final tick step has started arms a `retry` wake, since that step's tick may read the job before GitHub marks it ended. A work job that dies after a tick saw it alive, with no final tick of its own, is judged by the next tick after GitHub ends it (at the latest its `timeout-minutes`), with the cron behind it. The stint's job is read at most once a tick per Objective, and only for one with no work job alive; the tick reads each run's jobs once, and one runs listing serves every stint that began within 15 minutes of another. A vanished stage that left a sign the network was not what ended it is not relaunched (`endedNotLost`, read from the stint's `work ()` job as GitHub's jobs API gives it, its `conclusion` and `steps[]`, never a log): on the Action that job concluded `cancelled` or `timed_out` (a person, or the job's timeout: a stop, which keeps the vanished Block), or it failed before Pendulum ran, which is relaunched once (a checkout's or a token mint's 5xx, a runner not acquired, may pass), the step kept on the relaunch record, and Blocks with the cause `setup` naming the step when the relaunch's job fails at the same step (GitHub never started it: no step and no runner; or GitHub's `Set up job` failed; or a step failed before Pendulum's own work step, the step that `uses: clockgrove/pendulum@…` with `mode: work`, placed by reading the workflow file at the job's commit, one read only for a job that failed after its set-up: `Set up job` is step 1 and the job's steps follow in order, whatever they are named); on the sandbox its record says the stage ended. A job with no failed step of its own (its runner went away), whose Pendulum step failed with no exit written, or whose failed step cannot be placed because the workflow file cannot be read (the log says so) is lost. The dispatcher starts the work again as a trusted Draft removal would: the Objective goes Running again, a new stint, and a work stage resumes its branch and PR (on a cloud sandbox, in the Objective's recorded sandbox), within `max_usd` like any stage. A relaunch spends like a pick: none starts while today's spend has reached `daily_usd` (it waits, unblocked, for the UTC day's turn, its `daily-cap` wake, or for a spend that can be read) or while `max_concurrent` is reached, and relaunches go before new picks. At most twice since a person last started the Objective (applied its label, started its draft, or restarted it), counted in a record Pendulum owns on the issue (marker ``, each try naming that start), so a dispatcher that restarts keeps the count and a person's start begins a new one. So one start can spend up to 3 × `max_usd` on stages lost this way before the person is mentioned. Past that it Blocks, whatever the caps, and the notice says how many relaunches were tried: cause `outage`, the person mentioned, when the stage ended on one; a vanished stage gets the vanished Block (`worker job vanished`, cause `pendulum`) with the count. A write the relaunch needs that fails (its record, its labels, the Block) is tried again on the next tick, never turned into a Block. An Objective whose timeline the dispatcher cannot read is left as it is until a read succeeds: a vanished one stays Running, as any Running Objective whose Running time is unread does, and an outage-Blocked one stays Blocked on its stage's notice, which mentions no one; there is no fallback Block for that. On the Action, the stint's `work ()` job is looked up in the run the relaunch record names (each relaunch records its dispatcher's run), else among the 10 newest runs created in the hour up to the stint's start; one not found is no sign either way, so the stage is relaunched. A stopped or draft Objective is never relaunched, nor is a restarting one (a vanished one gets the vanished Block, and its restart goes ahead). A Block whose newest notice is anything but a stage's `outage` notice is never relaunched. Every other command (the Action's dispatcher, doctor, setup, the launcher) keeps the client's bound above. -GitHub's primary rate limit spent is an outage of one quota whose end GitHub states (`lib/network.mjs`, on the same wait): a 403 or 429, or GraphQL's `RATE_LIMITED`, with `x-ratelimit-remaining: 0`, an `x-ratelimit-reset` and no `Retry-After`, when GitHub's own count of that quota, read at once from `GET /rate_limit` with the same token (not counted against the primary rate limit, though it can count toward the secondary one, so it is not read again while the process holds that quota spent until the answer's reset or later), has none remaining; its reset is the count's. The quota read is the one the answer names (`x-ratelimit-resource`). A count with some remaining is no primary limit, whatever the answer says (a secondary limit, or a 403 for another reason on the last quota point), and keeps the retries above, as a `Retry-After` does; when the count cannot be read, the answer's own headers stand, as GitHub documents them. A quota is the host, GitHub's resource for the request (REST's core, GraphQL, search, code search, read from its path) and the token, so a spent GraphQL quota holds no REST call, and the notice App's or the agent's token none of the local token's. The reset is read on this machine's clock through the answer's `Date` header. In every process the error carries the code `RATE_LIMIT_SPENT` and the reset time; the process's record of a quota's reset is its latest answer, gone once the quota answers. In a work or review stage and in `serve`, the request that meets it is no try: it, and every other request against that quota, waits until the reset plus one to ten seconds, one sleep for all callers and no probe, with one log line when the limit is met and one when it has reset; then each goes again, a create included, since the refusal did nothing. A refusal that comes after the stated reset has passed here waits 5, 10, 20, 40 and then 60 seconds instead; one within a minute of a reset whose new reset is that near is the same wait, unlogged, while a quota spent again until a later reset is a new wait with its own two lines. A reset past the stage's in-place bound (fifteen minutes on the local route, its work deadline elsewhere) is not waited for: requests against that quota fail at once until the reset, its other quotas go on, and the stage ends on the first call that cannot go on without it. On the local route it ends `paused` with the reset in its `result.json`, and `serve` resumes it once the reset has passed, without a probe (LOCAL.md). On the Action and a cloud sandbox it Blocks with the External cause `provider-quota`, naming the reset; the Block is a GitHub write too, so a stage whose reset comes before its deadline plus twelve minutes (the job keeps fifteen after its deadline, which also pay for the steps before and the upload after) waits for it first, and with a later reset the Block's one write fails, and the dispatcher, once the reset lets it read GitHub again, relaunches the stage as one lost with no exit (`lib/relaunch.mjs`, above). A `provider-quota` Block is never relaunched: it mentions the person, who re-applies the label after the reset. The App token's mint carries the same code, only when the count, read with the App's JWT, says none remaining: with no count its answer is a rate limit with no stated end, since a refusal of the mint can meet the last quota point. A spent rate limit cuts no harness pass off. `serve` waits for the reset of a quota its own reads meet with no bound, so its ticks read, resume and start nothing until then. Every other command keeps the client's bound and gets the error with its code: the Action's dispatcher then starts nothing that tick, logs one line (`GitHub's API rate limit is spent until