Branch health — agent reference

A read-only watch on each Product's default branch on GitHub (the Factory bet's module M1, quick win H1). Every poll derives one state per Product (red, unknown or green) from the check runs and commit statuses on the branch head and from each workflow's runs, state and schedule. It keeps one episode per failing, disabled, overdue or waiting spell of a workflow, mirrored as one Portfolio blocker fact.

It reads through gh api --method GET only. It never writes to GitHub, never asks gh for a token, never reruns, pauses or re-enables anything, and records an observed signature for each episode, never a cause.

Status: Accepted local implementation: independent Astra reviews and combined checks passed. No live polling, scheduling or delivery. Acceptance and evidence.

• Source: src/branch-health.ts (derivation, episodes, the journal record, the Portfolio mirror) and src/branch-health-github.ts (the gh reader, response shapes, the read plan, trigger analysis and cron schedules)
• Tests: test/branch-health.test.ts , test/branch-health-github.test.ts , test/branch-health-replay.test.ts and the adversary's test/branch-health-adversarial.test.ts . What each covers: Tests and helpers.
• Helpers: test/helpers/fake-gh.mjs, test/helpers/branch-health-recording.ts, test/helpers/branch-health-portfolio.ts; fixtures in test/fixtures/branch-health/ (replay.json says how the copied capture is read)
• Design: <local evidence archive> §2 (KR2's episode, onset and closing rules), §3 (M1) and §4 (H1's acceptance)
• Human page: guide

Intelligence: none — Health, episodes and signatures are fixed rules over what GitHub reports; a model would guess at causes where only observed signatures are allowed.

What it hides

• Reading GitHub. ghCliReader spawns a named gh executable once per GET, with no shell, a timeout and a byte bound. Its arguments are the fixed GH_ARGUMENTS (api --method GET --include, a JSON Accept, a pinned API version, --) and the path. Its environment is explicit: ghEnvironment passes PATH, HOME, GH_CONFIG_DIR, GH_TOKEN, GITHUB_TOKEN and GH_HOST only, and the reader refuses GH_DEBUG and DEBUG. It parses the status line, headers and JSON body; a Link header only says whether a next page exists, and the next path is built here. Standard error is drained and dropped, so nothing gh prints there is kept.
• The read plan. readProduct reads one Product in a fixed order. First come the branch head (commits/<branch>), the head's check runs (up to 3 pages) and its combined status, then the workflows (up to 2 pages). For each workflow not disabled by a person it reads the file's schedule (contents/<path>) and the runs on the branch, page after page while the triggers read so far are not answered or, the runs have not reached the persisted workflow scan boundary or any open episode's readBackTo, up to 5 pages. A listing cut short by that choice or by its bound may hide a trigger whose latest run is older than every run read, so each branch event it did not reach is then read on its own (event=, one page each). Last come the jobs (up to 3 pages each) of the red runs not yet accounted for (for an open episode, its own red runs it has not read), newest first and 20 a poll, the rest at later polls; then of up to two successful runs on the head that might close an episode, retaining candidate reads so older useful runs are eventually examined: at most 22 runs a workflow.
• Identity and totals. A check run or combined status naming another commit than the head, a run naming another workflow (or, on an event's page, another event), jobs naming another run or commit, or a workflow file at another path make that read malformed: evidence about something else is never taken for this head or run. A listing whose pages declare a total that the items read do not match is cut short as malformed, never taken as whole.
• Trigger analysis. Runs count only on the branch and from a branch event (push, schedule, workflow_run, workflow_dispatch, repository_dispatch, dynamic); merge-queue and release runs are left out, since they test a queue branch or a tag, not the branch. A GitHub-managed workflow (dynamic/…) is read for dynamic runs only, the one event its runs have in the recorded capture. A run is red when completed as failure, timed_out or startup_failure, green when success; anything else (skipped, cancelled, neutral, running) is no evidence either way. Each event is analysed by completion time, with attempt order distinguishing retries. New failure spells during the watch are retained, including failures followed by success between polls; spells already ended before that workflow's first scan are baseline history. A cancelled or unfinished run on the current head remains unknown until newer conclusive evidence supersedes it.
• Check identity. The latest run of each check on the head stands. For GitHub Actions a check is a job name within one workflow: each check run's suite is traced to its workflow through the runs read, and an untraced one is a job name within its suite. A check run that names no suite is never superseded. Another app's check is its name, as GitHub reads a required check.
• Cron schedules. schedulesOf reads cron: lines of a workflow file and refuses to guess: a file that mentions a schedule without a cron it can parse is unreadable. parseCron takes five numeric fields with ranges, lists and steps (no names or macros); nextFiring finds the next minute in UTC within 400 days, either day field matching when both are restricted, as cron does. A dynamic workflow has no file; its schedule is GitHub's and is not checked.
• The record. One journal aggregate per Product, branch-health:product:<productId>, holds the last poll, the health derived by the last poll that changed it, the episodes (every open one and the 16 most recently closed) and, per workflow, its scan boundary and newest accounted red run. Its stored shape is sf-branch-health/2; older records are refused, not migrated implicitly. A snapshot of what a poll read is never kept; its SHA-256 over a key-sorted serialisation is.

Public interface

src/branch-health.ts:

src/branch-health-github.ts:

Stored layout. Commands branch-health/poll/<productId>/<pollId> (the poll ID is the poll's start instant), one a Product a poll: a full payload of the health, every kept episode, workflow scans and the accounted red runs, or, when nothing but the time changed, an unchanged payload with the content digest. Events: branch-health.polled; branch-health.episodes-opened (each episode with its workflow, signature, onset, detection, repository, latest red run and first failed step) and branch-health.episodes-closed, 50 episodes each at most; branch-health.state-changed. Mirror: collector branch-health, stable blocker ID the episode ID, branch-health/w<workflow>/<head, 12 hex>/r<first red run>.<attempt> for a red spell or …/<cause>-<detection instant> for no signal. blockerSource maps each logical version to a Portfolio source revision of 1–1,000; later generations use an /source/<generation> record suffix while retaining the blocker ID. A refused episode mirror does not prevent unrelated mirrors, and a repeated poll retries it.

Invariants and guarantees

1. GET only, and no token is printed. Every request is gh with GH_ARGUMENTS and a path built by githubPaths from checked parts; ghCliReader refuses any other path (an absolute URL, a leading dash, a dot segment, a path outside repos/) before spawning. Nothing asks gh for a token, standard error is never kept, and a failure is recorded as a reason code. Tests: the fake gh refuses every other method, any field or input, --paginate, auth token and --show-token. The replay's GETs are all accepted, with only allowed environment names, and a token set in the environment appears in no journal byte or report.
2. Bounded, refused whole. Pages, bytes and time are bounded (GITHUB_READ_LIMITS); a response over its byte bound is refused whole (too-large), never cut short. Tests: the oversized, hung and malformed cases; a poll that reads over 1 MiB records only its digest, and five pages bound each listing.
3. Unknown is never green. A request refused (401 unauthenticated, 403 forbidden, 403 with the rate limit spent or 429 rate-limited), failed, timed out or malformed is unknown, never an empty listing; a listing whose next page was not read is incomplete. A later page of runs that fails, or a trigger the runs listing did not reach whose own page could not be read, is a gap (runs-unread), whatever was read before it. A red run's jobs cut at their page bound are unknown, never "no failing job". An event's own page that was refused, failed or malformed, or that names a next page while holding no run, is a gap too, never an event without runs; so is a run listing cut short that holds no run. A page's declared total that the items read do not match, or evidence that names another commit, workflow, event or run, is malformed. Each gap becomes a HealthReason, and any reason or open episode keeps the Product from green. Tests: truncated check runs, 401 on check runs, 403 on workflows, a spent rate limit, 403 on runs and on a later page of runs, 401 and no answer on the head; the adversary's cut jobs listing; totals that do not match for check runs, workflows, runs and jobs; a check run, a status and jobs naming another commit or run; an event's own page malformed (empty or not), refused, or empty with a next page.
4. Green only on complete evidence. Green needs a readable head carrying at least one passing check or status (neutral and skipped are no pass), nothing failed, pending, cancelled, stale or awaiting action (checks-unsettled), every listing read to its end (for a workflow's runs: every branch event's latest run read), every schedule read and run at least once, and no open episode. A head with no check (no-check-on-head) or only skipped ones (no-passing-check) is unknown. A same-named job of another workflow never hides a failed check. A red check or status on the head makes the Product red whatever else passed. Tests: the positive control; four ways to stay unknown; Family Watch red despite its passing status; the adversary's same-named checks, action_required and stale, and a trigger beyond the first page; a re-run of the same workflow's job superseding its failure, and a cancelled one or one naming no suite that does not.
5. Signatures within one trigger. A red workflow's episode begins at the earliest spell start among its red events. Compared with that event's last green: new-head-red when the green was on another head, same-head-red on the same head, unclassed when there was never a green in a whole listing. When a red event's last green is out of reach, the signature is unclassed and the onset unknown. A signature is kept as observed at detection and is never a cause. Tests: the three signatures, a green of another event ignored, and out of reach; Pasta's Alpha within its workflow_run event.
6. Onset and detection. A red spell's onset is its first failed run's completion (failed-run). An overdue schedule's is its expected run plus 1 hour (overdue): the next cron firing after the last scheduled run. A schedule that has never run on the branch in a whole history has no date to count from (GitHub dates the workflow, not its cron line), so it opens no episode and keeps the Product unknown (schedule-never-ran). A waiting run's onset is its creation plus 1 hour (waiting). A workflow disabled for inactivity has an unknown onset (GitHub does not date it), as has a spell reaching past the runs in reach; notAfter bounds it. Detection counts from the first poll (detectedAt) and is never earlier than a known onset: a run that failed while the poll was reading is detected at its failure.
7. One episode per spell. A workflow may have several open spells when a later failure begins before older failing jobs have proven recovery. Each keeps its identity and observed onset. spellEnd records the first following success; it is not proof that the failing jobs passed. Failures are owned by completion chronology, including retries of older runs. An episode retains its read and unread job obligations. Accounted frontiers advance only after continuous history has been examined; they never discard another open episode. Workflow scan boundaries persist across closure, move only after a complete enough read, and move back when an older run is pending. An owner-disposed failure remains unknown if re-enabled without a newer run (reenabled-red).
8. Closing. A red episode closes only on a successful run on the current head, after its latest red run (or a retry of that run), whose jobs were read to their end, in which every failing job it recorded succeeded and at least one job succeeded. A job is known by its whole name (the SHA-256 of the name GitHub gives, FailingJob.key), never by its label, and a name that more than one job of the run holds passes only when each of them succeeded. Its failing jobs must be complete: every red run of it (each retained red attempt belonging to its failure period) read to its end, its spell's start in reach, no more than 100 failing jobs and 1,000 red runs, and its workflow's runs read back, at this poll, to its readBackTo. That is the newest run the last poll that reached back read or, when older, the oldest run that was still running then; for a red spell whose first red run the listing did not reach (only that event's own page), that first red run. Until a poll's listing reaches it, a run between two polls may be unread: readBackTo stays, the failing jobs are incomplete, and an episode of any kind closes only if its workflow is disabled by a person or removed; once more than five pages of runs lie between, no poll ever reaches it. An unread red attempt remains an obligation even when its run is retried; its own attempt's jobs are read separately. That run's own retry closes it as passed-on-retry ("cause unresolved"); otherwise it is recovered. A no-signal episode closes once its condition ended: a disabled one on a successful run on the head after its detection; a waiting one only when nothing waits over an hour, on a successful run completed after its detection; an overdue one only on a successful scheduled run on the head after its detection. A workflow disabled by a person or deleted, one missing from a whole workflow listing, or an overdue schedule removed from its file closes as owner-disposition, apart from recovery. A green run that skipped the failing jobs, a run on an old head, or a push run during an overdue spell closes nothing. Tests: each case, and the adversary's; 17 failing jobs; a job that failed only in an earlier red run; 25 red runs read over two polls; jobs alike in their first 120 characters, in spacing or but for a tab, and one name held by two jobs; a run that failed between two polls behind 100 successful ones; a failed second page, then 520 runs past the page bound; a run still running at one poll that failed behind 100 more.
9. Flags, never merges. Runaway: at least 6 red runs by a bot (…[bot]) on one head completing within the 24 hours before the poll, unknown when the runs in reach cover less than that and fewer are seen. A failing step shared by two open episodes, in any Products, is flagged on each with its partners; the episodes stay separate. Tests: 6, 5 and 6 by a person; both reconciles.
10. One command a Product a poll. A poll is recorded only if later than the recorded one (else conflict), and a poll at the instant already recorded is replayed only when its repository and branch match: nothing is read or derived again, and its recorded episodes are mirrored. A changed repository or branch returns conflict, with no fetch or mirror for that Product; other Products can still proceed. A result unchanged but for the time records only that the poll happened, keeping the health of the poll that last changed it (and moving lastGreen while green). The decision re-validates the payload: new episodes start at revision 1 detected at this poll or, later, at their onset; open episodes are never dropped (every episode that closes at a poll is kept with it, however many; earlier closures fill what is left of 16), closed ones never reopen, revisions and accounted red runs never go back.
11. The mirror. After the command, every kept episode's current blocker revision is written to the Portfolio, one episode at a time so a refusal cannot block unrelated episodes; an identical revision is a duplicate there, so repeating it every poll costs nothing and repairs a lost mirror. A revision moves when the blocker's content changes, and an open one is republished at least every 12 hours so the Portfolio never shows it stale. The fact names no one responsible (responsible: null), so it is never owner-required; its affected IDs carry the workflow, head, signature, onset and flags, and nextAction states the signature as a suspicion and links the latest red run's log with its first failed step.
12. Stored state is checked, never repaired. Every read and decision re-validates the record; a Product whose record fails is reported corrupt and left as it is, and the others are still polled.

Failure semantics

Journal errors other than version and command conflicts propagate unchanged.

Trust scope

Established, on this Mac with Node 26.8.1, in tests only:

• The replay of the recorded capture of six repositories (29 September 2026, read through a fake gh) gives the states the bet recorded:
  • Family Watch red despite a passing status, and Pasta's Alpha new-head red and runaway;
  • both reconciles same-head red with their shared step, and Tally's smoke tests no signal with the onset unknown;
  • Focus Sentinel and the Factory unknown, none green, and one blocker fact per episode.
• A read-only reader against a fake gh that refuses anything but a GET and never prints a token; unknown for truncation, 401, 403, rate limits, timeouts, oversize and malformed answers.
• Closing only on the failing jobs passing on the current head, matched by their whole names, with the runs read back without a gap to where the last poll left off, and with retry and owner disposition apart; one episode per spell across closures, re-enabling and a moving head; per-Product isolation of corrupt records; bounded events and mirror batches.

Composition

• Depends on: the Command journal (execute, readAggregate, readHistory, canonical JSON); the Portfolio (Portfolio.recordObservations, PORTFOLIO_LIMITS); Node's child_process, crypto and buffer.
• Used by: the Owner digest, which reads readBranchHealth, openedSince, HEALTH_REASONS, runUrl and the types; its blocker facts reach Required actions and blockers and the Dashboard through the Portfolio. Nothing in src/ calls poll.

Changing it safely

What must stay true

• A change to the argument list, the environment or the path rules changes what reaches gh: every request must stay a GET with no field, body or token request. Keep the fake gh's refusals in step with any new argument.
• The episode ID, the stored shape and the event types are what the owner digest and the Portfolio key on: a change to any of them is a protocol revision, not an edit in place.
• Keep accounted frontiers, per-workflow scans and retained episode obligations together: no one of these proves that all earlier failures were read.
• Workflow scans and an open episode's readBackTo keep failures between polls from going unread: it moves only at a poll whose listing reached it, and a closure needs that poll to have reached it.
• The fixtures under test/fixtures/branch-health/ are the recorded capture byte for byte (their SHA-256 are in replay.json); never edit them, and record a new capture beside them instead.

Tests and helpers

Focused tests: node --test test/branch-health.test.ts test/branch-health-github.test.ts test/branch-health-replay.test.ts test/branch-health-adversarial.test.ts, then test/owner-digest.test.ts and test/intelligence.test.ts. Every change also needs the steps in AGENTS.md's documentation obligations.

Run the local commands. Live use remains separately commissioned.