pr-agent-server/.hermes/plans/2026-09-21-upstream-auto-sync.md

# Upstream Auto-Sync — Auto Pull + Merge for Fork Repos

Status: implemented in `scripts/pr-queue-worker.py` (2026-09-21).
User decisions: interval **1 hour**, sync PRs **do** get the Claude Code auto-fix.

## Goal
For every repo the GitHub App is installed on whose GitHub metadata says
`fork: true`, pull the commits the upstream (parent) repo has that the fork lacks
and MERGE them into the fork's default branch — with conflict resolution, CI
verification and deduped notifications. No new cron/service: the existing
`pr-queue-worker.py` tick (every 5 min) runs it, gated by a per-repo interval.

## Fork state at build time (live)
| Fork | Parent | To merge | Fork divergence |
|---|---|---|---|
| `asepharyana/shiro-neko` | `zakirkun/shiro-neko` | 4 | 26 |
| `asepharyana/hermes-agent-mission-control` | `sharbelxyz/hermes-agent-mission-control` | 0 | 8 |

Both default branches are unprotected; the real shiro-neko merge conflicts in 14
files (`src/tools.ts`, `src/ui/App.tsx`, `src/tests…`).

## Design decisions (with reasons)
1. **Merge, never rebase** — preserves fork history/divergence (skill
   `fork-upstream-sync`).
2. **Inside `pr-queue-worker.py`** — the worker already owns the atomic cron
   lock, installation tokens and Discord plumbing; the sync is STEP 0 of the same
   tick, bounded to `max_per_tick = 2` forks, oldest-attempt-first so the budget
   rotates fairly.
3. **1h interval per repo** — the compare API is checked every tick (cheap), a
   merge attempt only when the interval elapsed AND the upstream tip changed
   (`last_attempt_sha`), so a failed/skipped sync is not retried every 5 minutes.
4. **Conflicted merges go to Claude Code** — `resolve_conflicts: true`. The
   prompt encodes the `fork-upstream-sync` rules (merge hunks by hand, never
   wholesale `--ours/--theirs`, strip UTF-8 BOM, run the repo's typecheck+tests
   before committing) plus the `merge-reconciler` impartiality contract (classify
   every hunk: disjoint-intent / same-question-different-answer / superseded;
   change nothing outside conflict markers; report every decision).
   Claude never pushes — the harness pushes.
5. **Clean merges get a quality pass** — `ai_fix_after_merge: true` runs one
   Claude Code pass over the merged files and commits
   `fix: auto-fix code quality [skip ci]`. On the PR path the normal worker AI
   fix applies (user decision), so sync PRs are treated like any other PR.
6. **Push path: owner PAT first, App token second** — the App has
   `contents:write` but NOT `workflows:write`, and the shiro-neko merge touches
   `.github/workflows/*`, so an App-token push is rejected. Clones use the App
   token; pushes use the gh CLI PAT (`_fetch_gh_token()`).
7. **Protected branch → PR path** — App tokens get 403 (not 404) on the
   branch-protection endpoint, so protection is detected from the PUSH result
   (GH006 / "protected branch" / required-status-check markers) and falls back to
   pushing a `upstream-sync-<ts>` branch + opening a PR that the normal pipeline
   finishes. Duplicate PRs are avoided by scanning open PRs for that head prefix.
8. **CI verify with sha-guarded auto-revert** — `verify_ci: true`. After a direct
   push, later ticks check the fork's CI at our merge sha; if it is still the tip
   and CI failed, the branch is force-pushed back to `pre_merge_sha` and Discord
   is notified. Never reverts when a human pushed on top; never applies to the
   protected/PR path; watch stops after `verify_ci_max_age_h = 6h`.
9. **Discord**: sync events go to the same `pr-agent-ops` webhook as the run
   reports (synced / PR opened / reverted / skipped-once).
10. **`merge_pr` PAT fallback** — a PR merge that changes workflow files is also
    a workflow-file push, so a 403 on the App merge retries with the PAT.

## Scope
- `scripts/pr-queue-worker.py` — new `# Upstream Fork Auto-Sync` section (config,
  discovery, compare, merge, conflict-resolve, push, PR path, verify/revert,
  orchestrator) + STEP 0 in `main()` + CLI flags.
- `scripts/test_pr_queue_sync.py` — new: 46 assertions over the orchestration.
- State: `/tmp/pr-queue-sync-state.json`; workdirs `/tmp/pr-queue-sync-work/`.
- No changes to `server/` (Bun), systemd units or the cron list.

## State shape
```json
{"owner/fork": {
  "last_sync_ts": 0, "last_attempt_sha": "", "last_merged_upstream_sha": "",
  "skip_reason": "", "notified": false,
  "pending_verify": {"sha": "", "pre_merge_sha": "", "branch": "main", "pushed_at": 0}
}}
```

## CLI (manual/dev)
```bash
python3 scripts/pr-queue-worker.py --sync-status
python3 scripts/pr-queue-worker.py --sync-only asepharyana/shiro-neko --dry
python3 scripts/pr-queue-worker.py --sync-only asepharyana/shiro-neko
```
`--dry` runs the whole flow (clone, merge, Claude conflict resolution) and stops
before pushing, leaving the prepared workdir in `/tmp/pr-queue-sync-work/<repo>`.

## Verification
- `python3 -m py_compile` clean.
- `python3 scripts/test_pr_queue_sync.py` → 46/46 (gating, clean merge, conflict
  resolution, failed resolution skip+dedupe, protected→PR, CI green/red/foreign-
  commit/running, fork discovery, push-error classification, config override).
- Live dry run against the real fork: clone + upstream fetch + conflicted merge +
  Claude Code resolution, verified with the repo's own `bun run typecheck`/`bun test`.
- Live production: the 5-minute cron picks it up on the next tick after the push
  (the cron wrapper ff-only pulls this repo and execs the repo copy).
- Regression guard for the bug the dry run caught: compare head ref must be
  `{owner}:{branch}` — a full `owner/repo:branch` head 404s.

## Out of scope
- Syncing non-default branches; pushing fork→upstream; scheduled rebase option.