From 1d3fdad9165b675dce3d3a5379b5b4d28bfa9d8d Mon Sep 17 00:00:00 2001 From: Chad Saunders Date: Thu, 12 Nov 2026 13:29:37 -0700 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20[fix]=20reads:=20a=20lane's?= =?UTF-8?q?=20malformed=20or=20refused=20read=20fails=20its=20call,=20not?= =?UTF-8?q?=20the=20run?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - a payload that misses its --kind shape exits 64 for every kind, not only those in FORMS; quota gets a form - a 403/404, unknown GraphQL field or unresolvable resource exits 64 on the first attempt instead of halting - a 401, bad token or missing scopes still halts at once; rate-limit 403s still retry then halt; SB_GITHUB_READ_STRICT keeps halting on all of these - seen in a downstream run: one lane's quota --jq read and one 403 halted every card --- scripts/super-board-github-read.py | 37 +++++++-- scripts/super-board-lane.sh | 2 +- skills/super-board/references/run-workflow.md | 14 ++-- tests/test_github_reads.py | 79 ++++++++++++++++++- workflows/super-board-wave.js | 4 +- 5 files changed, 120 insertions(+), 16 deletions(-) diff --git a/scripts/super-board-github-read.py b/scripts/super-board-github-read.py index 863df6e0..06655460 100644 --- a/scripts/super-board-github-read.py +++ b/scripts/super-board-github-read.py @@ -5,10 +5,14 @@ reads cannot reset it. Permanent query/auth errors stop on the first attempt. The halt file is shared through the main checkout, including linked worktrees. Only an explicit new run clears it with --resume after preserving the old reason. -Mutations never enter this retry helper. For the agent-facing kinds in FORMS, a -payload that fails its shape on every attempt is the caller's malformed read, not -an outage: that call exits 64 with the valid form and the run keeps going. Scripts -whose commands are fixed set SB_GITHUB_READ_STRICT=1 to keep halting on it. +Mutations never enter this retry helper. A payload that fails its shape on every +attempt is the caller's malformed read, not an outage: that call exits 64 (with the +valid form when FORMS has one) and the run keeps going, whatever its --kind. So is +a read GitHub refuses for this query alone (HTTP 403/404, an unknown GraphQL field, +a resource the token may not see): it exits 64 on the first attempt. Only a refusal +every read will hit (HTTP 401, bad credentials, missing scopes) halts at once. +Scripts whose commands are fixed set SB_GITHUB_READ_STRICT=1 to keep halting on all +of these: a fixed command that stops working is an outage. """ from __future__ import annotations @@ -46,6 +50,7 @@ class GitHubErrors(ValueError): 'if you pushed in between, re-take the metadata'), 'state': 'issue view --json state --jq .state', 'merge-state': 'pr view --json state,headRefOid,mergeCommit', + 'quota': 'api rate_limit (no --jq: the payload must stay JSON)', 'prs-open': 'pr list --state open --json number,title,body,url,headRefName,files', 'prs-merged': 'pr list --state merged --json number,title,body,url', 'issues-closed': 'issue list --state closed --json number,title,body,stateReason', @@ -124,10 +129,26 @@ def permanent_error(text): return False return re.search(r'Cannot query field|Unknown (?:argument|type)|Syntax Error|Parse error on|' r'GRAPHQL_VALIDATION_FAILED|undefinedField|variableRequiresValidType|' + r"Field '[^']+' doesn't exist on type|" r'HTTP 40[134]|Bad credentials|requires authentication|Resource not accessible|' r'Could not resolve to (?:a|an) |missing required scopes', text, re.I) is not None +def every_read_fails(text): + """A refusal every read will hit, whoever made it: the run cannot go on.""" + return re.search(r'HTTP 401|Bad credentials|requires authentication|missing required scopes', + text, re.I) is not None + + +def strict(): + return bool(os.environ.get('SB_GITHUB_READ_STRICT')) + + +def caller_failure(why, kind): + form = f' Valid form: --kind {kind} -- {FORMS[kind]}' if kind in FORMS else '' + return ValueError(f'{why}; this call failed, the run continues.{form}') + + def require(condition, why): if not condition: raise ValueError(why) @@ -341,6 +362,10 @@ def read(args, kind='json', meta=None, recovering=False): except ValueError: pass if permanent_error(diagnostic): + if not strict() and not every_read_fails(diagnostic): + status = re.search(r'HTTP [0-9]{3}', diagnostic) + raise caller_failure('GitHub refused this read' + (f' ({status[0]})' if status else '') + + ' for this query or resource alone', kind) halt('GitHub rejected a required read (query, authentication, or permission error); fix it before restarting', attempt, operation) if result.returncode: shape_only = False @@ -361,8 +386,8 @@ def read(args, kind='json', meta=None, recovering=False): if attempt < 3: print(f'[github-read] {last}; retry {attempt + 1}/3', file=sys.stderr) time.sleep(max(0, delay) * attempt) - if shape_only and kind in FORMS and not os.environ.get('SB_GITHUB_READ_STRICT'): - raise ValueError(f'{last}; this call failed, the run continues. Valid form: --kind {kind} -- {FORMS[kind]}') + if shape_only and not strict(): + raise caller_failure(last, kind) halt(f'{last}; stopped after 3 failed attempts', 3, operation) diff --git a/scripts/super-board-lane.sh b/scripts/super-board-lane.sh index 01dd34a8..e6d250d6 100755 --- a/scripts/super-board-lane.sh +++ b/scripts/super-board-lane.sh @@ -176,7 +176,7 @@ Resolved skill report: {json.dumps(skills)} Config: {config_path} Card: {json.dumps(card)} Read .claude/skills/{skill}/SKILL.md and .claude/skills/super-board/references/run.md → {section} lifecycle; follow all its board, branch, worktree, comments, test and merge requirements. -Source .claude/bin/super-board-gh-guard.sh and use its quota checks. Required GitHub reads go through .claude/bin/super-board-github-read.py; a read that misses its --kind shape exits 64 for that call only and prints the valid form, so fix the read. A --kind diff read needs --meta from a --kind metadata read first. Check --check before new writes, migrations and merges; exit 79 means status=halted, no more GitHub calls, preserve claims/worktree/card/approval. Never retry a mutation. +Source .claude/bin/super-board-gh-guard.sh and use its quota checks. Required GitHub reads go through .claude/bin/super-board-github-read.py; a read that misses its --kind shape, or that GitHub refuses for that query alone (403, 404, unknown field), exits 64 for that call only and prints why, so fix the read; a 401, bad token or missing scopes halts the run. A --kind diff read needs --meta from a --kind metadata read first. Check --check before new writes, migrations and merges; exit 79 means status=halted, no more GitHub calls, preserve claims/worktree/card/approval. Never retry a mutation. Use .claude/bin/super-board-card.sh for board reads/moves and .claude/bin/super-board-pr-body.sh for owned PR blocks; follow writing-standard.md and pr-author-notes.md. Use your own worktree under .claude/worktrees/; never edit the main checkout. Clean up on ordinary exit, preserve work on halt/interruption. {backend.label} adaptation: do not launch Claude or other sub-agents. Perform preflight, classification, independent review and truth-check duties inline. This changes the execution host, never the evidence requirements, confidence threshold or merge policy. diff --git a/skills/super-board/references/run-workflow.md b/skills/super-board/references/run-workflow.md index bcf00577..cbe7f7da 100644 --- a/skills/super-board/references/run-workflow.md +++ b/skills/super-board/references/run-workflow.md @@ -46,11 +46,15 @@ use the lane launcher's sandbox settings, including an external submodule git di Required reads use `.claude/bin/super-board-github-read.py --kind -- `. Three total attempts means the first attempt plus two retries of that same read; -unrelated successful calls do not reset its failures. Invalid GraphQL queries, -authentication, and permission errors stop immediately. Do not retry mutations. -A payload that misses an agent-facing `--kind` shape (`READ_SHAPES` in -`workflows/super-board-wave.js`) exits 64 for that call only, printing the valid -form; it never halts the run. Fixed-command scripts set `SB_GITHUB_READ_STRICT=1`. +unrelated successful calls do not reset its failures. Do not retry mutations. +A lane's malformed read fails that lane's call only (exit 64), never the run: a +payload that misses its `--kind` shape after three attempts, for every kind +(`READ_SHAPES` in `workflows/super-board-wave.js` lists the valid forms), and a +read GitHub refuses for that query alone (HTTP 403 or 404, an unknown GraphQL +field) on the first attempt. A refusal every read would hit (HTTP 401, a bad +token, missing scopes) halts at once with exit 79, and a rate-limit 403 halts +after three attempts. Fixed-command scripts set `SB_GITHUB_READ_STRICT=1` and keep +halting on all of these. Exit **79**, a workflow result with `halted: true`, or a failed `--check` ends this run. Check the helper's `--check` before claims, board/comment writes, each new diff --git a/tests/test_github_reads.py b/tests/test_github_reads.py index a551e2e4..9381533d 100644 --- a/tests/test_github_reads.py +++ b/tests/test_github_reads.py @@ -61,12 +61,77 @@ def test_recovery_resets_each_logical_read(self): self.assertFalse(self.halt.exists()) def test_permanent_graphql_error_is_not_retried(self): - r = self.read([{'rc': 1, 'err': 'GraphQL: Cannot query field wrong on type Query'}], - command=['api', 'graphql', '-f', 'query=query { wrong }']) + # A bad field is that caller's query, not an outage: it fails the call, never the run. + for err in ['GraphQL: Cannot query field wrong on type Query', + "GraphQL: Field 'wrong' doesn't exist on type 'Issue' (repository.issue.wrong)"]: + with self.subTest(err=err): + self.log.unlink(missing_ok=True) + r = self.read([{'rc': 1, 'err': err}], command=['api', 'graphql', '-f', 'query=query { wrong }']) + self.assertEqual(r.returncode, 64, r.stderr) + self.assertEqual(self.log.read_text(), '1') + self.assertFalse(self.halt.exists()) + self.env['SB_GITHUB_READ_STRICT'] = '1' + self.log.unlink() + r = self.read([{'rc': 1, 'err': err}], command=['api', 'graphql', '-f', 'query=query { wrong }']) + self.assertEqual(r.returncode, 79, 'fixed-command scripts still halt') + self.assertEqual(self.log.read_text(), '1') + self.env.pop('SB_GITHUB_READ_STRICT') + self.halt.unlink() + + def test_refusal_for_one_query_fails_only_that_call(self): + # A lane's 403 on a PR or a resource the token cannot see halted the whole run. + for err in ['gh: Upgrade to GitHub Pro or make this repository public to enable this feature. (HTTP 403)', + 'gh: Resource not accessible by integration (HTTP 403)', 'gh: Not Found (HTTP 404)', + 'GraphQL: Could not resolve to a PullRequest with the number of 999. (repository.pullRequest)']: + with self.subTest(err=err): + self.log.unlink(missing_ok=True) + r = self.read([{'rc': 1, 'err': err}], command=['api', 'repos/x/y/rules/branches/main']) + self.assertEqual(r.returncode, 64, r.stderr) + self.assertEqual(self.log.read_text(), '1', 'no retry') + self.assertEqual(r.stdout, '') + self.assertIn('this call failed, the run continues', r.stderr) + self.assertFalse(self.halt.exists(), 'one lane refused must not halt other lanes') + self.env['SB_GITHUB_READ_STRICT'] = '1' + r = self.read([{'rc': 1, 'err': 'gh: Not Found (HTTP 404)'}], command=['api', 'repos/x/y/pulls/9']) + self.assertEqual(r.returncode, 79, 'fixed-command scripts still halt') + + def test_refusal_every_read_hits_still_halts(self): + for err in ['gh: Bad credentials (HTTP 401)', 'gh: Requires authentication (HTTP 401)', + 'gh: Your token has not been granted the required scopes; missing required scopes [read:project]']: + with self.subTest(err=err): + self.halt.unlink(missing_ok=True) + self.log.unlink(missing_ok=True) + r = self.read([{'rc': 1, 'err': err}], command=['api', 'repos/x/y/pulls/1']) + self.assertEqual(r.returncode, 79, r.stderr) + self.assertEqual(self.log.read_text(), '1') + self.assertTrue(self.halt.exists()) + + def test_rate_limit_403_still_retries_then_halts(self): + r = self.read([{'rc': 1, 'err': 'gh: API rate limit exceeded for user (HTTP 403)'}], + command=['api', 'repos/x/y/pulls/1']) self.assertEqual(r.returncode, 79) - self.assertEqual(self.log.read_text(), '1') + self.assertEqual(self.log.read_text(), '3') + + def test_shape_miss_on_any_kind_fails_only_that_read(self): + # A quota read with a --jq that prints text had no form, so it halted the run. + r = self.read([{'out': 'graphql=4000/5000 rest=4900/5000\n'}], 'quota', + ['api', 'rate_limit', '--jq', '"graphql=\\(.resources.graphql.remaining)"']) + self.assertEqual(r.returncode, 64, r.stderr) + self.assertIn('Valid form: --kind quota -- api rate_limit', r.stderr) + self.assertFalse(self.halt.exists()) + # A kind with no form still fails only the call. + for out, kind in [('[]', 'object'), ('{"items":[]}', 'items'), ('{}', 'permission')]: + with self.subTest(kind=kind): + self.log.unlink(missing_ok=True) + r = self.read([{'out': out}], kind) + self.assertEqual(r.returncode, 64, r.stderr) + self.assertEqual(r.stdout, '') + self.assertIn('this call failed, the run continues', r.stderr) + self.assertFalse(self.halt.exists()) def test_successful_exit_with_malformed_or_partial_payload_halts(self): + # Fixed-command scripts (strict): a payload they cannot use is an outage. + self.env['SB_GITHUB_READ_STRICT'] = '1' for out, kind in [('{"resources":{"graphql":null,"core":null}}', 'quota'), ('{"items":[{"id":"I","content":{}}],"totalCount":1}', 'items'), ('{"items":[]}', 'items'), ('{"items":[],"totalCount":1}', 'items'), ('{"data":{},"errors":[{"message":"partial"}]}', 'json')]: @@ -77,6 +142,11 @@ def test_successful_exit_with_malformed_or_partial_payload_halts(self): self.assertEqual(r.returncode, 79) self.assertEqual(self.log.read_text(), '3') self.assertEqual(r.stdout, '') + # GitHub's own error payload is an outage for every caller, strict or not. + self.env.pop('SB_GITHUB_READ_STRICT') + self.halt.unlink(missing_ok=True) + r = self.read([{'out': '{"data":{},"errors":[{"message":"partial"}]}'}]) + self.assertEqual(r.returncode, 79, r.stderr) def test_agent_shape_mismatch_fails_only_that_read(self): # #32: a malformed agent read is not an outage; zero comments is a valid read. @@ -216,7 +286,9 @@ def test_diff_lines_with_line_like_characters_are_complete_evidence(self): def test_corrected_query_can_resume_without_erasing_original_failure(self): bad = ['api', 'graphql', '-f', 'query=query { wrong }'] + self.env['SB_GITHUB_READ_STRICT'] = '1' self.assertEqual(self.read([{'rc':1,'err':'Cannot query field wrong'}], command=bad).returncode,79) + self.env.pop('SB_GITHUB_READ_STRICT') original = self.halt.read_text() self.env['READ_RESPONSES'] = json.dumps([{'out':'{"resources":{"graphql":{"remaining":5000,"reset":0},"core":{"remaining":5000,"reset":0}}}'}]) result = subprocess.run(['python3',str(HELPER),'--resume','--kind','json','--', @@ -244,6 +316,7 @@ def test_failed_closed_card_reconcile_keeps_claim_and_lock(self): self.assertEqual(self.log.read_text(),'4','one state read, three failed project reads, no claim release') def test_dedupe_capped_or_malformed_data_is_never_no_match(self): + self.env['SB_GITHUB_READ_STRICT'] = '1' for data in [[{}], [{'number': n+1, 'body':'old'} for n in range(200)]]: self.halt.unlink(missing_ok=True); self.log.unlink(missing_ok=True) result = self.read([{'out':json.dumps(data)}],'dedupe', ['issue','list','--json','number,body']) diff --git a/workflows/super-board-wave.js b/workflows/super-board-wave.js index e7047595..2f310d92 100644 --- a/workflows/super-board-wave.js +++ b/workflows/super-board-wave.js @@ -50,7 +50,9 @@ const READ_SHAPES = [ `- PR body+head: --kind body -- pr view --json body,headRefOid`, `- PR metadata: --kind metadata -- pr view --json files,labels,body,additions,deletions,changedFiles`, `- issue state: --kind state -- issue view --json state --jq .state`, - `A read whose output misses its shape exits 64 for that call only and prints the valid form: fix the read, do not halt.`, + `- GitHub quota: --kind quota -- api rate_limit (no --jq)`, + `- PR merge outcome: --kind merge-state -- pr view --json state,headRefOid,mergeCommit`, + `A read whose output misses its shape, or that GitHub refuses for that query alone (403, 404, unknown field), exits 64 for that call only and prints why: fix the read, do not halt. A 401, bad token or missing scopes halts the run (exit 79).`, ].join('\n') const READ_FAILURE = READ_SHAPES + '\n' + `Verification-readiness exit 9 means missing/unusable config.verify_commands: preserve card/worktree/approval/claims, report status=halted (preflight verdict=halted), stop dispatch, repair project configuration before explicit restart; no Build bounce or automatic retries. ` + `Required GitHub reads use .claude/bin/super-board-github-read.py: three total attempts, exit 79 means run halted. Check --check before any GitHub write, migration, or merge. On exit 79 preserve worktree/card/approval/claims, make no more GitHub calls, and report status=halted (preflight verdict=halted). Never retry a mutation. Config: ${input.configPath}.` From 587690482fee6774eb1cd11c3a1e9b897e54a204 Mon Sep 17 00:00:00 2001 From: Chad Saunders Date: Thu, 12 Nov 2026 14:17:38 -0700 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20[fix]=20reads:=20kinds=20out?= =?UTF-8?q?side=20FORMS=20keep=20halting=20for=20fixed-command=20callers?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - a shape miss or a 403/404 fails only the call for the lane-facing kinds in FORMS (now incl. quota); script-only kinds (issue-history, items, fields...) still halt - keeps super-collect intake safety: a malformed issue history still stops before any write (test_collect_intake_safety.py) - test: fixed-command kinds halt on a shape miss and on a refusal --- scripts/super-board-github-read.py | 20 +++++++++---------- skills/super-board/references/run-workflow.md | 4 ++-- tests/test_github_reads.py | 13 +++++++----- 3 files changed, 20 insertions(+), 17 deletions(-) diff --git a/scripts/super-board-github-read.py b/scripts/super-board-github-read.py index 06655460..f6b99480 100644 --- a/scripts/super-board-github-read.py +++ b/scripts/super-board-github-read.py @@ -5,14 +5,14 @@ reads cannot reset it. Permanent query/auth errors stop on the first attempt. The halt file is shared through the main checkout, including linked worktrees. Only an explicit new run clears it with --resume after preserving the old reason. -Mutations never enter this retry helper. A payload that fails its shape on every -attempt is the caller's malformed read, not an outage: that call exits 64 (with the -valid form when FORMS has one) and the run keeps going, whatever its --kind. So is -a read GitHub refuses for this query alone (HTTP 403/404, an unknown GraphQL field, -a resource the token may not see): it exits 64 on the first attempt. Only a refusal -every read will hit (HTTP 401, bad credentials, missing scopes) halts at once. -Scripts whose commands are fixed set SB_GITHUB_READ_STRICT=1 to keep halting on all -of these: a fixed command that stops working is an outage. +Mutations never enter this retry helper. For the agent-facing kinds in FORMS, a +payload that fails its shape on every attempt is the caller's malformed read, not +an outage: that call exits 64 with the valid form and the run keeps going. So is a +read GitHub refuses for this query alone (HTTP 403/404, an unknown GraphQL field, +a resource the token may not see): it exits 64 on the first attempt. A refusal +every read will hit (HTTP 401, bad credentials, missing scopes) still halts at once. +Kinds outside FORMS serve scripts whose commands are fixed and keep halting; those +scripts also set SB_GITHUB_READ_STRICT=1 to halt on the agent-facing kinds. """ from __future__ import annotations @@ -362,7 +362,7 @@ def read(args, kind='json', meta=None, recovering=False): except ValueError: pass if permanent_error(diagnostic): - if not strict() and not every_read_fails(diagnostic): + if kind in FORMS and not strict() and not every_read_fails(diagnostic): status = re.search(r'HTTP [0-9]{3}', diagnostic) raise caller_failure('GitHub refused this read' + (f' ({status[0]})' if status else '') + ' for this query or resource alone', kind) @@ -386,7 +386,7 @@ def read(args, kind='json', meta=None, recovering=False): if attempt < 3: print(f'[github-read] {last}; retry {attempt + 1}/3', file=sys.stderr) time.sleep(max(0, delay) * attempt) - if shape_only and not strict(): + if shape_only and kind in FORMS and not strict(): raise caller_failure(last, kind) halt(f'{last}; stopped after 3 failed attempts', 3, operation) diff --git a/skills/super-board/references/run-workflow.md b/skills/super-board/references/run-workflow.md index cbe7f7da..1ff06566 100644 --- a/skills/super-board/references/run-workflow.md +++ b/skills/super-board/references/run-workflow.md @@ -48,8 +48,8 @@ Required reads use `.claude/bin/super-board-github-read.py --kind --