feat(upstream): explain why a PR cannot be planned early - #437

When the PR selected for early does not apply at the reconciled upstream boundary, the command stopped with a single line that gave nothing to act on:

$ node scripts/upstream-queue.ts early 11784 --through upstream/main
Selected #11784 cannot be applied at the upstream boundary.

That happens when the PR builds on upstream work the fork has not taken in yet, and the planner only looks for dependencies in the changes it replays after a successful apply.

The command now reports which of the PR's files conflict at the boundary and which earlier pending upstream PRs and direct commits change those files, in upstream order. Text output lists the first 20 and says how many remain; --json includes every source with its SHA, PR, and title. A plan that succeeds prints as before. The intake runbook's early paragraph describes the report.

Validation

• A new test in scripts/upstream-early.test.ts checks which sources the report lists: pending sources after the boundary and before the blocked PR whose files overlap the conflicting paths, including direct commits and directory prefixes, and not recorded or later sources.

• scripts/upstream-early.test.ts and scripts/upstream-queue.test.ts pass (21 tests); lint, formatting, and the scripts typecheck are clean.

• Against fetched fork main (495b7cfd5) and upstream main (b2b43bef7), the same command now prints:

  $ node scripts/upstream-queue.ts early 11784 --through upstream/main
  Fork 495b7cfd5; reconciled through d28077e58
  #11784 does not apply at the reconciled boundary. 16 of its files conflict there:
    apps/mobile/src/features/threads/ThreadFeed.tsx
    apps/mobile/src/features/threads/thread-work-log.tsx
    apps/mobile/src/lib/threadActivity.ts
    apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
    apps/server/src/orchestration/decider.ts
    apps/server/src/provider/Layers/ClaudeAdapter.test.ts
    apps/server/src/provider/Layers/ClaudeAdapter.ts
    apps/server/src/textGeneration/ThreadTitleContext.test.ts
    apps/server/src/textGeneration/ThreadTitleContext.ts
    apps/server/src/ws.ts
    apps/web/src/components/chat/MessagesTimeline.logic.ts
    apps/web/src/components/chat/MessagesTimeline.tsx
    apps/web/src/components/settings/SettingsPanels.tsx
    packages/client-runtime/src/state/environmentHttpAuth.test.ts
    packages/client-runtime/src/state/threadSnapshotHttp.ts
    packages/contracts/src/orchestration.ts
  Earlier pending upstream changes to those files: 110 PRs. Take them in first, or add their PRs to this plan.
    #9594 fix(connect): refresh HTTP credentials without reconnecting (#9594)
    #9894 fix(chat): show hours for long runs (#9894)
    #9933 fix(settings): share restart continuation across environments (#9933)
    #10092 fix(web): scale agent spawn rows with interface font (#10092)
    #9965 fix(web): keep the composer expanded until the thread can scroll (#9965)
    #9935 fix(web): align tool disclosure chevrons with expanded state (#9935)
    #10199 fix(mobile): size a chat image's frame before its bytes arrive (#10199)
    #10200 fix(web): size the chat image slot from server-reported dimensions (#10200)
    #10167 refactor(client-runtime): remove unused runtime exports and helpers (#10167)
    #10173 fix(mobile): restore live tool shimmer and add a Thinking row (#10173)
    #10210 fix(mobile): only make work rows expandable when the body adds something (#10210)
    #10211 fix(mobile): fold subagent lifecycle rows into one batch per spawn (#10211)
    #10212 fix(mobile): stop clipping expanded tool groups (#10212)
    #9875 feat: show provider usage limits with /usage-limits (#9875)
    #9561 fix(ui): unify loading and refresh feedback across clients (#9561)
    #10226 refactor(web): keep feature component helpers private (#10226)
    #9754 feat(settings): add shared project defaults and scoped overrides (#9754)
    #9895 feat(connections): balance new threads across connected machines (#9895)
    #10273 fix(mobile): stop the work log flickering during subagent runs and failing calls (#10273)
    #10271 fix(mobile): save linked media from chat (#10271)
    ... 90 more; --json lists every source.

  --json returns the same 16 paths and all 110 sources. early 5521 --through upstream/main, which plans successfully, prints the same summary as before.

Written by an agent (Claude Code, claude-opus-5-5).