Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Tell outside contributors what happens to their pull requests, and label issues our own automation files (#9378)
Garry Tanaab958d1a0f8
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 0000000000..1a344d44ad--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,5 @@+blank_issues_enabled: true+contact_links:+ - name: Community issues+ url: https://github.com/garrytan/gbrain/issues?q=is%3Aissue%20is%3Aopen%20-label%3Aagent-filed+ about: Open issues from the community, without the ones our own agents and CI file (label agent-filed). Check here before you file a duplicate.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 5681765bd7..6ddebe0884 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -805,23 +805,65 @@ gstack reads both from master, so a branch's edits take effect after it merges.2 MB ceiling. Those files stay covered by the privacy, gitleaks and docchecks, and every code, test and config line is still reviewed.-### How a contributor PR lands--Contributor PRs are never merged into master as-is. A maintainer folds the-change into a fix-wave PR, revises it there (tests, agent-facing errors,-conventions) and lands it with credit: the commit says `Contributed by @handle`-and carries a `Co-Authored-By:` trailer. Your PR stays open until then. When-the fix wave merges, a workflow closes your PR with a comment that links the wave.--The **Fix-wave gate** check enforces this. It fails every PR into master whose-head branch is not in `garrytan/gbrain` itself, and posts one comment saying-so when the PR opens. A red gate on a contributor PR is expected and is not a-judgment of the work. Maintainers' own branches (`capy/*`, `garrytan/*`) pass.+### How an outside pull request is handled++Thanks for sending one. Here is what happens to it, so nothing comes as a+surprise:++- **Documentation people read** (README, guides, docs pages; not Markdown that+ agents load, such as SKILL.md, AGENTS.md or prompts) can be merged as it is,+ after we check every link, command and install step in it.+- **Small, plainly correct fixes** (under about 40 lines, not counting tests:+ an error message, a typo, a small docs fix) are taken even when the gain is+ small. We rebuild them on current master and credit you as co-author: the+ commit says `Contributed by @handle` and carries a `Co-Authored-By:`+ trailer. We land at most one of these a day, so it can take a few days.+- **Everything else**, including all other code and anything that runs, we+ read as a detailed bug report. When we take it, we rebuild it on current+ master with the same credit.++Every pull request, ours and an outside documentation change alike, lands on+master as one squashed commit, with each outside author credited by a+`Co-authored-by:` trailer. When we rebuild a change, we close your PR with a+link to the PR that landed it. When we don't take one, we close it with a+short note saying why and what would change our answer. So apart from+documentation, "closed, not merged" is the normal outcome and doesn't mean+your work was turned down.++A larger change is much easier to take when it shows:++1. a way to reproduce the problem on current master, or a failing test;+2. what goes wrong for someone using gbrain because of it;+3. the version you saw it on (`gbrain version`).++A limit of 3 open pull requests applies only to someone whose recent pull+requests have mostly been closed without being taken. It never applies to+anyone who has had a pull request taken (merged or rebuilt) in the last 90 days.++Replies on behalf of the project come from the Capy app (`capy-ai[bot]`) or+a maintainer; a comment from any other account that calls itself triage does+not speak for gbrain. Every outside issue gets a first reply from us within 48+hours. A bug report we could not reproduce gets one follow-up question after+60 days, and is closed two weeks after that if nobody answers.++The same three things make a bug report easy to act on. To see what the+community has reported, without the issues our own agents and CI file, use the+[community issues](https://github.com/garrytan/gbrain/issues?q=is%3Aissue%20is%3Aopen%20-label%3Aagent-filed)+search: it lists open issues without the `agent-filed` label, which our CI+scripts add to every issue they open and which we have added to the open+issues our own agents filed.++The **Fix-wave gate** check runs on every PR into master. It fails every PR+whose head branch is not in `garrytan/gbrain` itself, and posts the comment+above when the PR opens. A red gate on an outside PR is expected and is not a+judgment of the work; a maintainer clears it when merging a documentation+change. Maintainers' own branches (`capy/*`, `garrytan/*`) pass.`maintainer-override` label: a human on the maintainer allowlist in`scripts/fix-wave-gate.ts` (it starts as `garrytan`) may apply it to pass the-gate for one PR a maintainer has decided may land from its fork (for example a-fix wave a maintainer opened from a fork); record the reason in a PR comment.+gate for one PR a maintainer has decided may land from its fork (for example an+outside documentation change, or a PR a maintainer opened from a fork); record+the reason in a PR comment.Bots never count, and the label only counts when the most recent`labeled` event was made by an allowlisted human. Every override is written tothe check's run log and step summary with who applied it and when. Process anddiff --git a/README.md b/README.mdindex acd7633baf..499d680a51 100644--- a/README.md+++ b/README.md@@ -366,7 +366,7 @@ Start with `gbrain doctor`. For database access failures, use `gbrain engine staRun `bun run test` for the fast loop, `bun run verify` for the pre-push gate, `bun run ci:local` to run the full Docker-backed CI stack locally. Detailed test discipline in [`CONTRIBUTING.md`](CONTRIBUTING.md).-Community PRs are batched into release waves rather than merged one-by-one — see the community-PR-wave process in [`docs/RELEASING.md`](docs/RELEASING.md). Contributor attribution stays attached via `Co-Authored-By:` trailers. We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md).+Outside documentation changes can be merged as they are. Code fixes we take are rebuilt on current master with the author credited as co-author (`Co-Authored-By:` trailers), and the original PR is closed with a link to the one that landed it; changes we don't take are closed with a note saying why. What to expect, and what makes a fix easy to take: [How an outside pull request is handled](CONTRIBUTING.md#how-an-outside-pull-request-is-handled). We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md). To browse community reports without our agents' own issues, use the [community issues](https://github.com/garrytan/gbrain/issues?q=is%3Aissue%20is%3Aopen%20-label%3Aagent-filed) search.If you find a bug or want a feature: open an issue first. Quick fixes (typo, doc bug, obvious regression) can go straight to a PR. Anything touching schema, retrieval ranking, MCP protocol, or the security boundary needs a design discussion in the issue first.diff --git a/docs/RELEASING.md b/docs/RELEASING.mdindex 80b93534de..7928bbaf8f 100644--- a/docs/RELEASING.md+++ b/docs/RELEASING.md@@ -927,7 +927,17 @@ to see what's actually in the PR before writing the body.## Community PR wave process-Never merge external PRs directly into master. Instead, use the "fix wave" workflow:+Fix waves built from outside PR lists ended on 2026-11-01. Each outside PR is+now triaged when it arrives, under the rules contributors see in+[CONTRIBUTING.md](../CONTRIBUTING.md#how-an-outside-pull-request-is-handled):+documentation people read may be merged as it is after a text read of every+link, command and install step; a small, plainly correct fix (under about 40+lines, not counting tests) is rebuilt on current master with credit, at most one+small PR a day; anything else is read as a report and rebuilt only when it has+proof and matters. Outside code is never checked out, run or merged. A rebuild+PR lists the outside PR on a `Supersedes #N` line so the+[closeout](#fix-wave-closeout) closes it with a link. The steps below are the+older batch procedure; steps 4 to 7 still apply to any rebuild PR.1. **Categorize** — group PRs by theme (bug fixes, features, infra, docs)2. **Deduplicate** — if two PRs fix the same thing, pick the one that changes fewer@@ -975,9 +985,11 @@ master unless its head repository is `garrytan/gbrain` or the `maintainer-overrilabel counts. Only maintainers can push to `garrytan/gbrain`, so GBRA thread PRs(`capy/*`) and `garrytan/*` branches pass; fork PRs fail whatever their branch iscalled. When a contributor PR opens, a second job posts one comment with the same-text as the failure: the work is welcome and the PR stays open, it lands through a-fix wave with credit (`Contributed by @handle` plus a `Co-Authored-By:` trailer), and-CONTRIBUTING.md "Where does my change go?" explains where changes belong.+text as the failure: how outside PRs are handled (documentation merged as it is+after a text read, small correct fixes rebuilt with credit, everything else read as+a report and rebuilt with credit when taken, `Contributed by @handle` plus a+`Co-Authored-By:` trailer), the proof a larger change needs, who the open-PR limit+applies to, and a link to CONTRIBUTING.md "How an outside pull request is handled".The workflow uses `pull_request_target`, so the workflow and`scripts/fix-wave-gate.ts` always come from the default branch: a PR that edits@@ -990,7 +1002,7 @@ repository (deleted fork) fails closed. The check re-runs on `opened`, `edited`,**`maintainer-override` label.** Who: a human on `MAINTAINERS` in`scripts/fix-wave-gate.ts` (starts as `garrytan`; changing it is a reviewed PR tomaster). When: only for a PR a maintainer has decided may land from its fork, such as-a fix wave a maintainer opened from a fork; record the reason in a PR comment. How it+an outside documentation change or a PR a maintainer opened from a fork; record the reason in a PR comment. How itis checked: the label counts only when the most recent `labeled` timeline event for itwas made by an allowlisted `User`; bots (`capy-ai[bot]`, `github-actions[bot]`, any`[bot]` login) never qualify, and removing the label fails the PR again. Audit: the rundiff --git a/docs/architecture/key-files/ci-health-and-test-guards.md b/docs/architecture/key-files/ci-health-and-test-guards.mdindex 4bd34ce625..0b6193fe83 100644--- a/docs/architecture/key-files/ci-health-and-test-guards.md+++ b/docs/architecture/key-files/ci-health-and-test-guards.md@@ -5,7 +5,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `.github/workflows/nightly-watch.yml` + `scripts/nightly-issue.ts` — nightly-red and master-red incidents. `workflow_run` fires only for master-branch completions; the `resolve` job admits scheduled runs and push-to-master runs of Test and E2E Tests from this repository (head repository checked) plus dispatch, and `nightly-issue.ts --resolve` turns every entry path into the target workflow id and track (`schedule`, `push`; a replay writes `push`); `watch` queues on one group per repository + workflow + track. `nightly-issue.ts --run-id <id> [--replay-issue <n>] [--dry-run]` routes the run (`routeRun`: pull-request, fork, other-branch and non-allowlisted push runs are refused with a next step). Scheduled runs keep one `Nightly red: <workflow>` issue (label `nightly-red`): open on red with job/step pairs, every failing test file with its reproduce line, sanitized error excerpts, the first red run, the last green SHA and compare link, a "Next step for the agent" and a JSON block; update while red; reopen on a flap; close only on a later green scheduled run with complete evidence where every previously failing job executed. Rows in `.github/nightly-known-red.tsv` (at most 3; race-hunt jobs refused) keep a matching incident open under `known-red`. A scheduled Test or E2E Tests run also feeds that workflow's open master-red issue. Push runs go to `scripts/lib/master-red.ts`. A ratchet test fails when a scheduled workflow is not watched. Tests: `test/scripts/nightly-issue.test.ts`. Process: `docs/RELEASING.md#nightly-red-issues`, `docs/ci-red-runbook.md`.- `.github/workflows/upgrade-matrix.yml` + `scripts/upgrade-matrix.ts` (modules in `scripts/upgrade-matrix/`) — upgrade-from-N matrix (GBRA-224 W2). `plan` resolves the candidate and from-versions (N-1, N-10, N-50, 30 days, stable) from release tags; `cell` installs a from-version with `bun install -g github:garrytan/gbrain` in an isolated HOME, seeds a brain, runs that release's `gbrain upgrade` against `github-fixture.ts` (per-cell bare mirror via git `insteadOf`, loopback tarball API, TLS fixture behind `HTTPS_PROXY`; every other host refused), then checks install identity, one build across a running serve, apply-migrations, schema head, doctor, canonical preservation (`snapshot.ts`), writes, keyed vector query on the mock provider and the old binary on the upgraded brain; `summarize` judges red/hold/green (`verdict.ts`, `known-exceptions.json`, the `W4 SWITCH POINT` for `doctor --alert`); `issue` keeps one `upgrade-break` issue. Tests: `test/scripts/upgrade-matrix.test.ts`. Docs: `docs/ci-upgrade-matrix.md`.-- `scripts/lib/gh-issue.ts` — the GitHub seam shared by the CI watchers. `inert()` makes run-derived text (job, step and test names, error text) safe to show an agent: control characters stripped, length capped, backticks and pipes replaced, mentions and links neutralized; `redactCredentials()` strips user:password from database URLs. `GitHubClient` is the one interface the watchers call (`restClient()` uses `GH_TOKEN`/`GITHUB_TOKEN` in Actions or the authenticated `gh api` locally; `download()` reads artifact archives without forwarding the token to blob storage). `findIssueByTitle` finds an issue by label and exact title, open first, else the most recently updated closed one; `listLabeled`, `getIssue` and `linkedPulls` (PRs cross-referencing an issue) back master-red and CI health; `fetchArtifactJson` + `readZipEntry` read one JSON file from a run artifact and return a reason instead of throwing.+- `scripts/lib/gh-issue.ts` — the GitHub seam shared by the CI watchers. `inert()` makes run-derived text (job, step and test names, error text) safe to show an agent: control characters stripped, length capped, backticks and pipes replaced, mentions and links neutralized; `redactCredentials()` strips user:password from database URLs. `GitHubClient` is the one interface the watchers call (`restClient()` uses `GH_TOKEN`/`GITHUB_TOKEN` in Actions or the authenticated `gh api` locally; `download()` reads artifact archives without forwarding the token to blob storage). `findIssueByTitle` finds an issue by label and exact title, open first, else the most recently updated closed one; `listLabeled`, `getIssue` and `linkedPulls` (PRs cross-referencing an issue) back master-red and CI health; `fetchArtifactJson` + `readZipEntry` read one JSON file from a run artifact and return a reason instead of throwing. `createIssue` adds `AGENT_FILED_LABEL` (`agent-filed`) to every issue it opens, so CONTRIBUTING.md's community-issues search can leave automation's issues out; `test/scripts/gh-issue-agent-filed.test.ts` fails if a script or workflow opens an issue any other way.- `.github/workflows/ci-health.yml` + `scripts/ci-health-report.ts` — CI health report. Reads one window (`--days`, default 7, or `--since/--until`, also dispatch inputs) of same-repository pull-request and push-to-master runs of test.yml and e2e.yml (runs, jobs, check-run annotations, issues; never logs, fork runs or fork artifacts), paging the whole window (`listRuns` splits a query over the 1000-result search cap). It reports first-attempt pass rates (`firstAttempt()`), the exit criteria (master >= 95%, PR >= 90%; met, missed or indeterminate when the window cannot be read in full), stress-gate failures, failure classes, cancellation and completion coverage, master-red time to first response, the nightly-watch residual, the test files with the most failure annotations, shard spread and the count of fork runs it did not read; an explicit window with a missed target opens a follow-up issue. Tests: `test/scripts/ci-health-report.test.ts`. Docs: `docs/ci-red-runbook.md#ci-health-report`.- `scripts/lib/master-red.ts` — master-red reconciliation for push-to-master runs of Test and E2E Tests (`PUSH_ALLOWLIST`). Each watch evaluates every completed push run above the high-water mark (`evaluated`: run number, then attempt) stored in the newest `Master red: <workflow>` issue's `master-red:json` block (`applyRun` folds runs; cancelled runs change nothing); a missing or malformed block is rebuilt from the actions API (`pendingRuns`). It opens on red with the suspect range (`suspectRange`: compare plus commit-to-PR lookups), updates while red, closes when every previously failing job (E2E Tests: every failing file, from the manifest) ran and passed with complete evidence, records an incident that opened and closed between watches, and keeps a not-run-since failure open with the manual-close step. A newest issue closed by hand while its block is red ends that incident (`closed_by_hand`): later runs are recorded on it as green, and only a new red run opens a new issue. `externalPass` lets a scheduled run or an issue-bound E2E replay clear failures. Closing without a merged linked repair PR opens `flake` issues (`flakeFor`, `flake:json`); `closeFlakes` closes one after its repair PR merged and a later complete run passed its file and arm. Writes re-read the issue first and re-plan when it moved; a create race closes the newer duplicate. Tests: `test/scripts/nightly-issue.test.ts`. Docs: `docs/ci-red-runbook.md`.- `scripts/lib/ci-run.ts` — one run's failure evidence (`collectEvidence`): jobs, failing jobs' annotations and, for test.yml and e2e.yml, the `ci-manifest` artifact, returned as structured records (job, step, every failing test file and identity) apart from sanitized excerpts; a cancelled job is not run (listed in `cancelled`) unless its annotation says it timed out, and a red run whose only failures are aggregators of cancelled jobs is `ignored`; with `complete`/`problems` (an unreadable page, annotation or manifest is incomplete evidence, never zero failures). A push run with a succeeded `reused-full-suite` job is judged by the run its `reuse.json` names (`checkRecord` from `scripts/ci-reuse.ts`, recorded attempt, identical commit tree): that run's succeeded jobs and complete `ci-manifest` stand in for the push, and any gap is incomplete. `reproduceCommand` builds `bun run test:stress <file> --iterations 10 [--postgres]` from a validated test path only. `exemptionRows` turns failing identities with an exact test name and signature into the stress gate's `<!-- gbrain-stress-exemption -->` records (backend per `stressBackend`, owner `agent on release duty`), written into master-red, flake and nightly-red bodies; `test/fixtures/nightly-watch/stress-exemption-contract.ts` vendors the gate's parser so the tests prove it accepts them.diff --git a/llms-full.txt b/llms-full.txtindex df61d9eba7..c6d2cf8271 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -4748,7 +4748,7 @@ Start with `gbrain doctor`. For database access failures, use `gbrain engine staRun `bun run test` for the fast loop, `bun run verify` for the pre-push gate, `bun run ci:local` to run the full Docker-backed CI stack locally. Detailed test discipline in [`CONTRIBUTING.md`](CONTRIBUTING.md).-Community PRs are batched into release waves rather than merged one-by-one — see the community-PR-wave process in [`docs/RELEASING.md`](docs/RELEASING.md). Contributor attribution stays attached via `Co-Authored-By:` trailers. We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md).+Outside documentation changes can be merged as they are. Code fixes we take are rebuilt on current master with the author credited as co-author (`Co-Authored-By:` trailers), and the original PR is closed with a link to the one that landed it; changes we don't take are closed with a note saying why. What to expect, and what makes a fix easy to take: [How an outside pull request is handled](CONTRIBUTING.md#how-an-outside-pull-request-is-handled). We credit every accepted contribution in [`CHANGELOG.md`](CHANGELOG.md). To browse community reports without our agents' own issues, use the [community issues](https://github.com/garrytan/gbrain/issues?q=is%3Aissue%20is%3Aopen%20-label%3Aagent-filed) search.If you find a bug or want a feature: open an issue first. Quick fixes (typo, doc bug, obvious regression) can go straight to a PR. Anything touching schema, retrieval ranking, MCP protocol, or the security boundary needs a design discussion in the issue first.diff --git a/scripts/fix-wave-closeout.ts b/scripts/fix-wave-closeout.tsindex 00ded46409..b3af55a24e 100644--- a/scripts/fix-wave-closeout.ts+++ b/scripts/fix-wave-closeout.ts@@ -76,13 +76,13 @@ export function isMergedWave(event: CloseoutEvent): boolean {export function closeoutMessage(handle: string, wave: number, waveTitle: string, credited: boolean): string {const credit = credited- ? ` with credit to you: the wave says \`Contributed by @${handle}\` and carries a \`Co-Authored-By:\` trailer.`+ ? ` with credit to you: that PR says \`Contributed by @${handle}\` and carries a \`Co-Authored-By:\` trailer.`: '.';return [COMMENT_MARKER,- `Thank you, @${handle}. Fix-wave PR #${wave} (${waveTitle}) merged into master and supersedes this PR, so the change it proposed has landed there${credit}`,+ `Thank you, @${handle}. Pull request #${wave} (${waveTitle}) merged into master and supersedes this PR, so the change it proposed has landed there${credit}`,'',- `I'm closing this PR because nothing is left for it to land, not because anything was wrong with it. If part of it didn't make it into #${wave}, reply here with what's missing and the next fix wave will pick it up.`,+ `I'm closing this PR because nothing is left for it to land, not because anything was wrong with it. If part of it didn't make it into #${wave}, reply here with what's missing and why it matters.`,'','This comment comes from the fix-wave closeout workflow.',].join('\n');diff --git a/scripts/fix-wave-gate.ts b/scripts/fix-wave-gate.tsindex 1aeb0c97fb..474d1ca7ae 100644--- a/scripts/fix-wave-gate.ts+++ b/scripts/fix-wave-gate.ts@@ -30,7 +30,7 @@ export const OVERRIDE_LABEL = 'maintainer-override';/** Humans who may apply the override label. Edit only through a reviewed PR to master. */export const MAINTAINERS: readonly string[] = ['garrytan'];export const COMMENT_MARKER = '<!-- fix-wave-gate -->';-const CONTRIBUTING_URL = 'https://github.com/garrytan/gbrain/blob/master/CONTRIBUTING.md#where-does-my-change-go';+const CONTRIBUTING_URL = 'https://github.com/garrytan/gbrain/blob/master/CONTRIBUTING.md#how-an-outside-pull-request-is-handled';interface Repo { id?: number; full_name?: string }interface Actor { login?: string; type?: string }@@ -54,15 +54,28 @@ export interface GateClient {}export function gateMessage(handle: string): string {+ const credit = 'credit you as co-author: the commit says `Contributed by @' + handle + '` and carries a `Co-Authored-By:` trailer with your name';return [COMMENT_MARKER,- `Thanks for this pull request, @${handle}. The work is welcome, and this PR stays open.`,+ `Thanks for this pull request, @${handle}. Here is how we handle outside pull requests, so you know what to expect:`,'',- 'gbrain does not merge contributor pull requests into master directly. A maintainer folds the change into a fix-wave PR, revises it there (tests, agent-facing errors, conventions), and lands it with credit to you: the commit says `Contributed by @' + handle + '` and carries a `Co-Authored-By:` trailer with your name. When that fix wave merges, this PR is closed with a comment that links it.',+ '- **Documentation people read** (not files agents load, such as SKILL.md or AGENTS.md) can be merged as it is, after we check every link, command and install step in it.',+ `- **Small, plainly correct fixes** (under about 40 lines not counting tests, such as an error message or a typo) are taken even when the gain is small. We rebuild them on current master and ${credit}. We land at most one of these a day, so it can take a few days.`,+ `- **Everything else**, including all other code and anything that runs, we read as a detailed bug report. When we take it, we rebuild it on current master with the same credit.`,'',- `You don't need to do anything else. To see where a change belongs and what the fix wave checks, read CONTRIBUTING.md, "Where does my change go?": ${CONTRIBUTING_URL}`,+ "When we rebuild a change, we close this PR with a link to the PR that landed it. When we don't take one, we close it with a short note saying why and what would change our answer. So apart from documentation, \"closed, not merged\" is the normal outcome and doesn't mean your work was turned down.",'',- 'This message comes from the fix-wave gate check, which stays red on contributor PRs by design.',+ 'For a larger change, show us:',+ '',+ '- a way to reproduce the problem on current master, or a failing test;',+ '- what goes wrong for someone using gbrain because of it;',+ '- the version you saw it on (`gbrain version`).',+ '',+ 'A limit of 3 open pull requests applies only to someone whose recent pull requests have mostly been closed without being taken. It never applies to anyone who has had a pull request taken (merged or rebuilt) in the last 90 days.',+ '',+ `More in CONTRIBUTING.md, "How an outside pull request is handled": ${CONTRIBUTING_URL}`,+ '',+ 'This comment comes from the fix-wave gate check. It is red on every outside pull request by design, and a maintainer clears it when merging a documentation change.',].join('\n');}diff --git a/scripts/lib/gh-issue.ts b/scripts/lib/gh-issue.tsindex 632eca64ea..1c4e0f3ed9 100644--- a/scripts/lib/gh-issue.ts+++ b/scripts/lib/gh-issue.ts@@ -9,6 +9,7 @@* - `GitHubClient` is the one seam both scripts call; tests pass a recorded* fake, production uses `restClient()` (fetch + GH_TOKEN/GITHUB_TOKEN in* Actions, or the authenticated `gh api` CLI for local dry runs).+ * - `createIssue` adds `AGENT_FILED_LABEL` to every issue it opens.* - `findIssueByTitle` looks an issue up through the list API by label and* exact title (open first, else the most recently updated closed one, so a* flapping workflow reopens its own issue).@@ -169,8 +170,11 @@ export async function findIssueByTitle(client: GitHubClient, label: string, titlexport const labelNames = (issue: Issue): string[] => (issue.labels ?? []).map(l => (typeof l === 'string' ? l : l.name));+/** On every issue our own automation opens, so the community's reports can be listed without it (CONTRIBUTING.md, "How an outside pull request is handled"). */+export const AGENT_FILED_LABEL = 'agent-filed';+export async function createIssue(client: GitHubClient, title: string, body: string, labels: string[]): Promise<Issue> {- return client.request<Issue>('POST', 'repos/{repo}/issues', { title, body, labels });+ return client.request<Issue>('POST', 'repos/{repo}/issues', { title, body, labels: [...new Set([...labels, AGENT_FILED_LABEL])] });}export async function updateIssue(client: GitHubClient, number: number, patch: { body?: string; state?: 'open' | 'closed'; labels?: string[] }): Promise<Issue> {diff --git a/scripts/lib/master-red.ts b/scripts/lib/master-red.tsindex 5f13802c0d..bc90906adb 100644--- a/scripts/lib/master-red.ts+++ b/scripts/lib/master-red.ts@@ -28,7 +28,7 @@* Docs: docs/RELEASING.md#master-red-issues, docs/ci-red-runbook.md#ci-issue-labels.*/import {- commentIssue, createIssue, ensureLabel, getIssue, inert, inertBlock, jsonBlock, linkedPulls, listLabeled, readJsonBlock, updateIssue,+ AGENT_FILED_LABEL, commentIssue, createIssue, ensureLabel, getIssue, inert, inertBlock, jsonBlock, linkedPulls, listLabeled, readJsonBlock, updateIssue,type GitHubClient, type Issue,} from './gh-issue.ts';import { collectEvidence, EXEMPTION_DAYS, EXEMPTION_MARKER, exemptionRows, plusDays, reproduceCommand, stressBackend, verdictOf, workflowFile, type EvidenceOptions, type FailedJob, type FailedTest, type RunEvidence, type RunInfo } from './ci-run.ts';@@ -520,7 +520,7 @@ async function writePlan(client: GitHubClient, repo: string, plan: MasterRedPlanstep.issue = (await createIssue(client, plan.title, renderMasterRed(step.state, repo), [MR_LABEL])).number;const older = step.action === 'create' && (await listLabeled(client, MR_LABEL, 'open')).filter(i => i.title === plan.title && i.number < step.issue!).sort((a, b) => a.number - b.number)[0];if (older) {- await updateIssue(client, step.issue, { body: `Duplicate of #${older.number}: two watches created this incident at the same time; #${older.number} carries the state. Nothing to do here.`, state: 'closed', labels: [] });+ await updateIssue(client, step.issue, { body: `Duplicate of #${older.number}: two watches created this incident at the same time; #${older.number} carries the state. Nothing to do here.`, state: 'closed', labels: [AGENT_FILED_LABEL] });throw new CreateRace(`#${step.issue} duplicated #${older.number}`);}}diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsvindex 1700216aea..487b37b8bc 100644--- a/scripts/structural-suites.tsv+++ b/scripts/structural-suites.tsv@@ -338,6 +338,7 @@ test/scripts/e2e-wiring.test.ts (file-level) 14 readFileSynctest/scripts/fix-wave-gate.test.ts fix-wave gate workflow 3 readFileSynctest/scripts/full-ci-workflow.test.ts full CI on pull requests 7 readFileSynctest/scripts/full-ci-workflow.test.ts master-push reuse of a passed full-suite run 2 readFileSync+test/scripts/gh-issue-agent-filed.test.ts agent-filed label 2 readFileSynctest/scripts/heavy-door-workflow.test.ts heavy door supply chain and coverage gates 8 readFileSynctest/scripts/native-lock-prebuilds.test.ts native lock distribution integrity 2 readFileSynctest/scripts/native-setup-toolchain.test.ts scripts/native/setup-toolchain.ts download budget 4 readFileSyncdiff --git a/scripts/upgrade-matrix.ts b/scripts/upgrade-matrix.tsindex 89c31a8a1c..a03da238fd 100644--- a/scripts/upgrade-matrix.ts+++ b/scripts/upgrade-matrix.ts@@ -21,6 +21,7 @@ import { join, resolve } from 'node:path';import { fetchReleases, hasEnoughHistory, RELEASE_TAG, resolveFromVersions, type Candidate, type FromVersion, type Profile, type Release } from './upgrade-matrix/versions.ts';import { cellId, runCell, type BrainShape, type Engine, type Fault, type Keys } from './upgrade-matrix/cell.ts';import { CHECKS, loadKnownExceptions, summarize, type CellSummary } from './upgrade-matrix/verdict.ts';+import { AGENT_FILED_LABEL } from './lib/gh-issue.ts';const REPO = 'garrytan/gbrain';const ROOT = resolve(import.meta.dir, '..');@@ -236,7 +237,7 @@ async function issue(): Promise<void> {await api('POST', '/issues/' + existing.number + '/comments', { body: 'Still red on ' + (s.candidate.tag ?? s.candidate.sha) + ': ' + s.red.join(', ') + '. ' + (s.harness.run_url ?? '') });console.log('updated #' + existing.number);} else {- const created = await api('POST', '/issues', { title, body, labels: [ISSUE_LABEL] }) as any;+ const created = await api('POST', '/issues', { title, body, labels: [ISSUE_LABEL, AGENT_FILED_LABEL] }) as any;console.log('created #' + created.number);}} else if (s.status === 'green' && existing?.state === 'open') {diff --git a/test/scripts/fix-wave-closeout.test.ts b/test/scripts/fix-wave-closeout.test.tsindex 8908df037c..e2215670a2 100644--- a/test/scripts/fix-wave-closeout.test.ts+++ b/test/scripts/fix-wave-closeout.test.ts@@ -79,7 +79,7 @@ describe('fix-wave closeout run', () => {expect(r.code).toBe(0);expect(calls).toEqual(['get 5085', 'comment 5085', 'close 5085', 'get 5089', 'comment 5089', 'close 5089']);expect(comments[5085]![0]).toContain(COMMENT_MARKER);- expect(comments[5085]![0]).toContain('Fix-wave PR #9000 (v0.60.70.0 fix wave 9)');+ expect(comments[5085]![0]).toContain('Pull request #9000 (v0.60.70.0 fix wave 9)');expect(comments[5085]![0]).toContain('`Contributed by @alice-example`');expect(comments[5089]![0]).not.toContain('Contributed by');expect(r.summary).toContain('#5085: closed (@alice-example, credited)');diff --git a/test/scripts/fix-wave-gate.test.ts b/test/scripts/fix-wave-gate.test.tsindex f9c3b120a6..9db22eeeab 100644--- a/test/scripts/fix-wave-gate.test.ts+++ b/test/scripts/fix-wave-gate.test.ts@@ -46,10 +46,17 @@ describe('fix-wave gate decision', () => {const { client, calls } = fakeClient();const r = await gate(load('fork-gbra-branch.opened.json'), client);expect(r.code).toBe(1);- expect(r.out).toContain('The work is welcome, and this PR stays open.');+ expect(r.out).not.toContain('stays open');+ expect(r.out).toContain('can be merged as it is, after we check every link, command and install step');+ expect(r.out).toContain('are taken even when the gain is small');+ expect(r.out).toContain('we read as a detailed bug report');+ expect(r.out).toContain('close this PR with a link to the PR that landed it');+ expect(r.out).toContain('what would change our answer');+ expect(r.out).toContain('a failing test');+ expect(r.out).toContain('never applies to anyone who has had a pull request taken (merged or rebuilt) in the last 90 days');expect(r.out).toContain('Contributed by @alice-example');expect(r.out).toContain('Co-Authored-By:');- expect(r.out).toContain('CONTRIBUTING.md#where-does-my-change-go');+ expect(r.out).toContain('CONTRIBUTING.md#how-an-outside-pull-request-is-handled');expect(r.summary).toContain('fail (fork)');expect(calls).toEqual([]);});diff --git a/test/scripts/gh-issue-agent-filed.test.ts b/test/scripts/gh-issue-agent-filed.test.tsnew file mode 100644index 0000000000..ebb1f8c71c--- /dev/null+++ b/test/scripts/gh-issue-agent-filed.test.ts@@ -0,0 +1,72 @@+/**+ * scripts/lib/gh-issue.ts createIssue + every issue filer in the repository.+ *+ * Protects: each issue our own automation opens carries the `agent-filed`+ * label, so CONTRIBUTING.md's "community issues" search (open issues without+ * that label) shows only community reports. The CI filers (nightly-issue.ts,+ * master-red.ts, ci-health-report.ts) open issues through createIssue, and+ * upgrade-matrix.ts names the label itself; the ratchet below fails if a+ * script or workflow opens an issue any other way.+ */+import { describe, expect, test } from 'bun:test';+import { readdirSync, readFileSync, statSync } from 'node:fs';+import { join, relative } from 'node:path';+import { AGENT_FILED_LABEL, createIssue, type GitHubClient } from '../../scripts/lib/gh-issue.ts';++const ROOT = join(import.meta.dir, '../..');++function recorder() {+ const calls: Array<{ method: string; path: string; body: { labels?: string[] } }> = [];+ const client: GitHubClient = {+ async request<T>(method: 'GET' | 'POST' | 'PATCH', path: string, body?: unknown): Promise<T> {+ calls.push({ method, path, body: body as { labels?: string[] } });+ return { number: 1, title: 't', state: 'open' } as T;+ },+ };+ return { client, calls };+}++function files(dir: string, keep: (p: string) => boolean): string[] {+ const out: string[] = [];+ for (const name of readdirSync(dir)) {+ const p = join(dir, name);+ if (statSync(p).isDirectory()) out.push(...files(p, keep));+ else if (keep(p)) out.push(p);+ }+ return out;+}++describe('agent-filed label', () => {+ test('createIssue adds the label to the caller\'s labels, once', async () => {+ expect(AGENT_FILED_LABEL).toBe('agent-filed');+ const { client, calls } = recorder();+ await createIssue(client, 'Nightly red: X', 'body', ['nightly-red']);+ await createIssue(client, 'Flake: y', 'body', ['flake', 'agent-filed']);+ await createIssue(client, 'z', 'body', []);+ expect(calls.map(c => [c.method, c.path, c.body.labels])).toEqual([+ ['POST', 'repos/{repo}/issues', ['nightly-red', 'agent-filed']],+ ['POST', 'repos/{repo}/issues', ['flake', 'agent-filed']],+ ['POST', 'repos/{repo}/issues', ['agent-filed']],+ ]);+ });++ test('no script or workflow opens an issue without the label', () => {+ const candidates = [+ ...files(join(ROOT, 'scripts'), p => /\.(ts|sh|js|mjs)$/.test(p)),+ ...files(join(ROOT, '.github'), p => /\.ya?ml$/.test(p)),+ ];+ const offenders: string[] = [];+ for (const p of candidates) {+ const rel = relative(ROOT, p);+ const text = readFileSync(p, 'utf8');+ if (/gh\s+issue\s+create|issues\.create\(/.test(text)) offenders.push(`${rel}: gh issue create / issues.create`);+ if (rel === 'scripts/lib/gh-issue.ts') continue;+ if (/['"`]POST['"`],\s*['"`](repos\/\{repo\})?\/?issues['"`]/.test(text) && !text.includes('AGENT_FILED_LABEL')) offenders.push(`${rel}: POST to the issues collection without AGENT_FILED_LABEL`);+ }+ expect(offenders).toEqual([]);+ expect(readFileSync(join(ROOT, 'scripts/upgrade-matrix.ts'), 'utf8')).toContain('labels: [ISSUE_LABEL, AGENT_FILED_LABEL]');+ for (const filer of ['scripts/nightly-issue.ts', 'scripts/lib/master-red.ts', 'scripts/ci-health-report.ts']) {+ expect(readFileSync(join(ROOT, filer), 'utf8')).toContain('createIssue(client');+ }+ });+});diff --git a/test/scripts/nightly-issue.test.ts b/test/scripts/nightly-issue.test.tsindex d71668656e..9d984a8de5 100644--- a/test/scripts/nightly-issue.test.ts+++ b/test/scripts/nightly-issue.test.ts@@ -73,7 +73,7 @@ describe('nightly-watch incidents', () => {expect(plan.action).toBe('create');const create = calls.find(c => c.method === 'POST' && c.path === 'repos/{repo}/issues')!;expect(create.body!.title).toBe('Nightly red: Heavy Tests');- expect(create.body!.labels).toEqual(['nightly-red']);+ expect(create.body!.labels).toEqual(['nightly-red', 'agent-filed']);const body = String(create.body!.body);expect(body).toContain('| `Heavy tests` | `Bootstrap offline Docker e2e (placeholder)` | failure | no |');expect(body).toContain('### Next step for the agent');@@ -397,7 +397,7 @@ describe('master-red: push-to-master runs', () => {expect(r.track).toBe('push');expect(r.masterRed!.action).toBe('create');const issue = masterIssue(w)!;- expect(labelNames(issue)).toEqual(['master-red']);+ expect(labelNames(issue)).toEqual(['master-red', 'agent-filed']);const state = mrState(issue);expect(state.status).toBe('red');expect(state.first_red).toMatchObject({ run_id: T.r8320.id, sha: T.r8320.head_sha });@@ -440,6 +440,7 @@ describe('master-red: push-to-master runs', () => {expect(issue.comments.at(-1)).toContain('No merged repair PR is linked');const flakes = w.labeled('flake');expect(flakes.map(f => f.title).sort()).toEqual(['Flake: test/managed-lint.test.ts', 'Flake: test/pack-relation-direction-engine.test.ts', 'Flake: test/persistence-history-fixture.test.ts']);+ for (const f of flakes) expect(labelNames(f)).toEqual(['flake', 'agent-filed']);const rec = readJsonBlock<FlakeRecord>(flakes[0]!.body, FLAKE_MARKER)!;expect(rec).toMatchObject({ schema: 'flake/v1', master_red_issue: issue.number, owner: 'agent on release duty', platform: 'linux' });expect(rec.reproduce).toMatch(/^bun run test:stress test\/[\w./-]+\.test\.ts --iterations 10 --postgres$/);@@ -928,7 +929,10 @@ describe('master-red: push-to-master runs', () => {const open = both.issues.filter(i => i.title === 'Master red: Test' && i.state === 'open');expect(open).toHaveLength(1);expect(both.labeled('master-red')).toHaveLength(1);- for (const twin of both.issues.filter(i => i.title === 'Master red: Test' && i.state === 'closed')) expect(twin.body).toContain(`Duplicate of #${open[0]!.number}`);+ for (const twin of both.issues.filter(i => i.title === 'Master red: Test' && i.state === 'closed')) {+ expect(twin.body).toContain(`Duplicate of #${open[0]!.number}`);+ expect(labelNames(twin)).toEqual(['agent-filed']);+ }});test('E2E Tests closes only when every previously failing test file was among the files a run executed and passed', async () => {