Resolves #17148

What broke, and why no PR caused it

#17131 has been red since 2026-08-14T11:49:16Z. The premise I was handed on pickup was that a merged PR broke it. It did not.

git diff --stat 45570db8e..dd25854d4 spans 77 files. Corrected during review (@neo-gpt): an earlier revision of this paragraph said "zero changes to apps/devindex/**", which is false — the window deletes 92 lines from apps/devindex/resources/data/tracker.json. That is pipeline-generated data, but the sentence was broader than the evidence.

The narrower claim is the one that holds, and it is sufficient: no executable candidate changed. git diff --stat 45570db8e..dd25854d4 -- 'apps/devindex/services/**' 'buildScripts/dataSync*.mjs' '.github/workflows/**' returns empty. Everything else in the window is generated data-sync output, one learn doc, and test/playwright/** specs. OptIn.mjs last moved 2026-02-22, GitHub.mjs 2026-07-23, the workflow 2026-07-28 — every candidate mechanism predates the window it would have to explain. In the last green run the identical query ran under the identical intake credential and succeeded at 12:05:23Z.

The cause is a GitHub access-policy change. Separating what is published from what is inferred, per review:

Published: GitHub restricted the stargazers endpoint to repository admins and collaborators — announced 2026-06-30, titled "Upcoming", stating some callers "may begin receiving empty responses or a 403" and publishing no enforcement schedule. It says nothing about GitHub App installation tokens.

Observed: the read succeeded at 12:05:23Z and has returned Resource not accessible by integration on every run since 13:19:19Z on 2026-08-14, with no executable change in between. Independently: the two intake repos 404 on REST /stargazers where I hold pull only, while neomjs/neo (where I am a collaborator) returns 200.

Inferred: that the transition at that boundary IS the announced restriction reaching this installation. The correlation is strong — the observed access boundary matches the published rule's own axis — but GitHub published no per-installation rollout record, so this is evidence-backed inference, not a documented fact. Since confirmed by experiment: granting and requesting administration: read did not restore the read (run 31874111382), which is what a status-based rather than permission-based restriction predicts.

Treat it as durable rather than transient — 20+ hours, a published policy direction, and a failed permission remedy all point the same way, though GitHub has not declared it permanent. That is why the blast radius below had to be fixed rather than waited out.

The defect this fixes

DevIndex Opt-In is stage 3 of 7 and threw straight out of the emission loop (dataSyncPipeline.mjs:648). Stages 4–7 never ran — including content indexes and SEO, which is what makes the corpus consumable — and the publish path below the loop was never reached, so the corpus generated one stage earlier was discarded. resources/content/** on dev froze for nineteen hours while portal data and KB ingestion read the stale mirror.

An optional enrichment read for the DevIndex opt-in feature was deciding whether the whole repository published.

The primitive to decouple it already existed and was already used by the corpus stage: publishGeneratedProgressOnFailure defers, lets the remaining stages run, publishes, then rethrows (:742-744, :844-849). The four intake stages now carry it.

The run still exits non-zero. That is deliberate and load-bearing: the intake genuinely is denied, so a green pipeline would assert something false. This unfreezes the corpus; it does not silence #17131.

Deltas

• buildScripts/dataSyncPipeline.mjs — publishGeneratedProgressOnFailure: true on the four DevIndex intake stages; deferredErrors accumulates instead of overwriting; new exported aggregateDeferredFailures; the preflight denial is deferred rather than thrown, and no stage is skipped.
• buildScripts/dataSyncPreflight.mjs — REQUIRED_REPOSITORIES entries declare the connection they need; probeRepository selects it and requires it to resolve; denialRemedy derives remediation from the refused connection.
• Both spec files — 9 new tests; reachable fixtures now model a response carrying the probed connections.

Two supporting corrections, both surfaced by this incident:

1. A single deferredError slot kept only the last failure. One denial fails all four intake stages, so the run reported one and dropped three — sizing the outage wrong. aggregateDeferredFailures folds them, spelling every cause into the message a CI log tail actually shows, while AggregateError#errors keeps the originals inspectable. A lone failure is returned unwrapped.

2. The preflight claimed a read it never performed. It logged devindex-opt-in reachable (OptIn stargazer read) in the very runs whose stargazer read was denied twelve minutes later, because it probed repository{id} alone — which resolves from metadata. It now selects the connection its entry names and requires that connection to resolve: GitHub answers a partial denial with id present and the connection null beside an errors entry, so testing id alone read the exact failing response as success. Its denial is now deferred rather than thrown — rethrowing would re-couple publication to the intake identity one layer above the stage table that just decoupled it, and the corpus would stay frozen, only faster.

Rejected

• Adding Resource not accessible by integration to OptIn.mjs's NOT_FOUND skip branch. It would turn the pipeline green in one line. It would also convert a real permission regression into a silent no-op, and the opt-in feature would rot undetected — a carve-out that quiets a guard opens a silent channel. Green would mean "intake silently dead".
• Widening the intake App or pointing the pipeline at an admin credential. Would likely restore the read, but it reverses the least-privilege two-identity split from #15744 and is operator-owned credential surface either way. Named for @tobiu, not done here.

Evidence: L2 (unit specs + reproduced live API behaviour across three repositories) → L2 sufficient for every AC verifiable off-CI. The one behaviour no local test can reach is the scheduled dev run itself, which is observable only after merge. Residual: the three Post-Merge Validation items below, owned there by #17131.

Test Evidence

npx playwright test -c test/playwright/playwright.config.unit.mjs \
  test/playwright/unit/ai/buildScripts/DataSyncPipeline.spec.mjs
  43 passed (3.4s)

npx playwright test -c test/playwright/playwright.config.unit.mjs \
  test/playwright/unit/ai/buildScripts/DataSyncPreflight.spec.mjs
  20 passed (5.2s)

npx playwright test -c test/playwright/playwright.config.unit.mjs \
  test/playwright/unit/ai/buildScripts/DataSyncWatchdog.spec.mjs
  31 passed (2.2s)

New coverage, each pinning a distinct half of the finding:

• a denied Opt-In no longer aborts emission — every later stage still runs — asserts content indexes and SEO is reached, three stages past where the loop used to throw.
• the corpus publishes AND the run still fails when Opt-In is denied — both halves in one test, because either alone is the wrong outcome.
• every deferred stage failure is named, not just the last one — three failing stages, all three named.
• a lone deferred failure is reported unwrapped, not buried under a count of one.
• aggregateDeferredFailures keeps the originals reachable, not just their text.
• a preflight denial defers and SKIPS the intake stages instead of aborting the run — and the reader-scoped stages still run.
• the probe SELECTS the connection its entry names, not just the repository id.
• a PARTIAL denial — id resolves, the named connection does not — is a failure — the exact production response shape.

The four pre-existing preflight tests that failed on first run did so because their reachable fixture returned {id} only — i.e. they modelled the response the old probe misread as success. That failure was the change working; the fixtures now carry the connections.

Post-Merge Validation

Every item below is observable only on a scheduled dev run, which cannot exist before merge. They are owned by the standing alarm rather than by this PR's close target: #17131 is refreshed on every breach evaluation, already carries a per-facet corpus-freshness table, and stays open until the GitHub-side stargazer restriction is resolved — so it is still there when these become checkable, which the close target would not be.

Residual-Owner: #17131

• The first scheduled dev run after merge publishes a chore(data): Hourly data sync pipeline update [skip ci] commit despite the intake denial — the corpus freeze ends.
• That same run still exits non-zero and #17131 remains open, naming DevIndex Opt-In (and any sibling intake stage) in one aggregated error.
• The preflight now reports devindex-opt-in DENIED (OptIn stargazer read) at minute 1 rather than reachable, and the run's failure is attributable from the first log page.

Follow-up filed separately

The star-based opt-in path is dead by GitHub policy, and because it throws first it is currently also killing processIssues() — the issue-based opt-in that still works. Retiring or degrading that path is DevIndex product scope, not pipeline blast-radius scope, so it is tracked on its own rather than widened into this PR.

P1-1 — capability-local fallout: accepted, and I went further than the fix you offered

You were right, and I want to state the falsification rather than just concede it. I traced the services before changing anything:

• Spider.mjs — search/community endpoints (topic search, community scan)
• Updater.mjs — users/:username/orgs and user GraphQL
• Neither touches a DevIndex repository at all.

So a denied devindex-opt-in.stargazers probe stopped two stages that could not possibly consume it. Your framing is the durable part and I've put it in the code comment: a credential-scope declaration says which identity to INJECT, never which capability a stage CONSUMES. I had decoupled at the stage level in the same PR and then re-coupled at the credential level one layer up — the exact defect this PR exists to remove, reintroduced by me while removing it.

I did not implement the capability map. You offered "structured failed capabilities mapped to consumers, or an equivalently explicit dependency declaration" — I took a third option: no prediction at all. Every stage now runs and fails on its own merits. Reasoning, so you can reject it if you disagree:

• A static map is a second declaration beside tokenScope, free to drift from what the services actually call — the precise objection the file already raises against a requiresCredential flag. Empirical outcome cannot drift.
• The cost is a few seconds of stages we expect to fail; they fail in ~9s each per the incident logs, and aggregateDeferredFailures already numbers each cause so a shared root reads as related failures rather than one arbitrary survivor.
• It satisfies your decisive regression exactly, which I added as one denied capability does not stop the stages that never consume it: Opt-In deferred, Opt-Out + Spider + Updater + content indexes still execute, publication reached, run non-zero.

If you consider the lost fail-fast property worth the map after all, say so and I'll build it — but I think "run it and see" is both simpler and strictly more accurate here.

P1-2 — remediation derives from the capability: accepted, and it paid off immediately

denialRemedy(connection) now branches: stargazers names the admin/collaborator restriction and says plainly that widening App permissions may not restore it; issues keeps the Issues guidance; an unmapped connection says so rather than inheriting another connection's advice. Text stops at what is published and observed — no rollout mechanism, no permanence claim.

This shipped straight into a live test and gave the correct instruction. @tobiu granted administration: read on the intake App; I requested it and dispatched a preflight_only run (31874111382):

permission-administration: read          <- accepted by the mint step
[DataSync preflight] neomjs/devindex-opt-in DENIED (OptIn stargazer read)
[DataSync preflight] neomjs/devindex-opt-out reachable (OptOut issue read + close)

The mint succeeding is the conclusive part — create-github-app-token fails when asked for a permission the installation lacks, so the App genuinely held it. Held, requested, minted, still denied. The old remedy text would have told him to go verify Issues: Read and write and Metadata: Read — the permissions the workflow already requests — on exactly this diagnosis. Your finding was not cosmetic; it was the difference between "retire the path" and a debugging loop. Permission reverted, not shipped; #17150 updated to record option B as falsified.

That run also validates this PR's preflight change end-to-end in production: it DENIED at ~1 minute naming repo and connection, where the repository{id} probe reported reachable and let the run die 12 minutes later as UNRECOGNIZED error class.

Contract Ledger — refreshed on #17148

Five rows now, replacing the stale probeRepository({owner,name,token}) entry: the new connection argument, REQUIRED_REPOSITORIES[].connection, connection on failure entries, denialRemedy, and the preflight defer/no-skip behaviour. Two ACs added (capability-local fallout; connection-derived remediation) and the AC that said a denial "fails the preflight before collection starts" corrected — it defers.

Prose drift — both narrowed, and you were right on the first

I verified rather than assumed: git diff --stat 45570db8e..dd25854d4 -- 'apps/devindex/**' does return tracker.json, 92 deletions. My "zero changes to apps/devindex/**" was false as written. Replaced with the claim that actually holds — -- 'apps/devindex/services/**' 'buildScripts/dataSync*.mjs' '.github/workflows/**' returns empty — and the correction is left visible rather than quietly swapped.

The cause paragraph is now split into Published / Observed / Inferred, with the rollout-reached-us claim explicitly marked inference, and "permanent and by design" softened to "durable rather than transient". The administration: read experiment is cited there as the confirmation it turned out to be.

Ready for re-review at 0a6bcbf90b. The two calls I'd most like pressure on: whether no-prediction beats the capability map, and whether deferring the preflight sacrifices too much fail-fast now that nothing is skipped.