Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 29 additions & 4 deletions scripts/super-board-github-read.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,12 @@
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.
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

Expand Down Expand Up @@ -46,6 +50,7 @@ class GitHubErrors(ValueError):
'if you pushed in between, re-take the metadata'),
'state': 'issue view <N> --json state --jq .state',
'merge-state': 'pr view <N> --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',
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -341,6 +362,10 @@ def read(args, kind='json', meta=None, recovering=False):
except ValueError:
pass
if permanent_error(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)
halt('GitHub rejected a required read (query, authentication, or permission error); fix it before restarting', attempt, operation)
if result.returncode:
shape_only = False
Expand All @@ -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 kind in FORMS and not strict():
raise caller_failure(last, kind)
halt(f'{last}; stopped after 3 failed attempts', 3, operation)


Expand Down
2 changes: 1 addition & 1 deletion scripts/super-board-lane.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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 <file> 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 <file> 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.
Expand Down
14 changes: 9 additions & 5 deletions skills/super-board/references/run-workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <shape> -- <gh args>`.
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 lane-facing
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
Expand Down
82 changes: 79 additions & 3 deletions tests/test_github_reads.py
Original file line number Diff line number Diff line change
Expand Up @@ -61,12 +61,80 @@ 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_agent_shape_miss_fails_only_that_read_fixed_kinds_halt(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 serves a fixed-command script: a payload it cannot use, or a
# refusal, is an outage there and still halts.
for out, kind in [('[]', 'object'), ('{"items":[]}', 'items'), ('{}', 'permission')]:
with self.subTest(kind=kind):
self.halt.unlink(missing_ok=True)
self.log.unlink(missing_ok=True)
r = self.read([{'out': out}], kind)
self.assertEqual(r.returncode, 79, r.stderr)
self.assertEqual(r.stdout, '')
self.halt.unlink(missing_ok=True)
r = self.read([{'rc': 1, 'err': 'gh: Not Found (HTTP 404)'}], 'items', ['api', 'repos/x/y/pulls/9'])
self.assertEqual(r.returncode, 79, r.stderr)

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')]:
Expand All @@ -77,6 +145,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.
Expand Down Expand Up @@ -216,7 +289,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','--',
Expand Down Expand Up @@ -244,6 +319,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'])
Expand Down
4 changes: 3 additions & 1 deletion workflows/super-board-wave.js
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,9 @@ const READ_SHAPES = [
`- PR body+head: --kind body -- pr view <N> --json body,headRefOid`,
`- PR metadata: --kind metadata -- pr view <N> --json files,labels,body,additions,deletions,changedFiles`,
`- issue state: --kind state -- issue view <N> --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 <N> --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}.`

Expand Down