upstream-sync

---
name: upstream-sync
description: Pull new work from stablyai/orca into this fork. Use whenever upstream has moved and Manta should pick up their bug fixes and features — before cutting a release, or on a schedule. The fork lives on a generated, rebranded mirror of upstream, so a sync is one merge, not a cherry-pick campaign.
---

# Syncing from upstream

Manta is a fork of `stablyai/orca` that renamed the product throughout and
added three things of its own: the self-hosted relay, the mobile
internationalization, and its own release CI. A sync takes upstream's fixes
and features and leaves those three alone.

## The shape of the fork

Measured on 2026-09-02 (22,774 comparable files, every number reproduced by a
second agent): **95.6% of the fork is identical to upstream once the brand is
normalized**, 86.4% of the rest differs by the rename alone, and the evidence
rule below reproduces 5,805 of those files with zero error. The fork's real
work is about 400 shared files and 234 of its own.

So the fork is kept as **upstream + a generated transform + a small patch set**:

- `refs/sync/mirror` — upstream's history with `brand_rule.py` applied to
  every commit, paths included. Upstream speaking Manta. **Extended, never
  rebuilt**: a commit already mirrored keeps its SHA (matched by its
  `Mirror-Of:` trailer) and only what upstream added is transformed. A mirror
  rebuilt from scratch renames a few blobs differently under newer evidence,
  every commit after that point changes SHA, and a pull request between the
  two histories has no merge base — GitHub can neither diff it nor run its
  checks. That was the first sync on this model; it is why the mirror is
  incremental now.
- `refs/sync/base` — the mirror commit the fork last merged.
- `main` — the mirror, the fork's own commits, and one merge commit per sync.

A sync extends the mirror and merges it into a branch cut from `main`. With
both sides speaking Manta, **every conflict is a real one**: the same code
changed on both sides. The rename cannot conflict, a file upstream deleted
cannot come back by accident, and there is no conflict-time rebrand to get
wrong. When upstream rewrites its history (a squash — it has happened once),
no trailer matches, the mirror is rebuilt whole, and that sync is a
bootstrap-shaped event: expect the merge to be large and read it.

## Doing it

```bash
.claude/skills/upstream-sync/sync-run.sh            # from a clean tree, any branch
```

It fetches upstream, stops if `refs/sync/base` already mirrors the tip, extends
the mirror (evidence = `main`, seconds for a normal week), cuts
`sync/upstream-YYYYMMDD` from `main`, and runs

```
git merge --no-ff refs/sync/mirror
```

On a clean merge it continues into `sync-finish.sh`. On conflicts it prints
them and stops. Resolve, `git commit`, then run `sync-finish.sh` yourself. In a
merge **`--ours` is the fork and `--theirs` is upstream**.

What conflicts look like, and what to do:

| where | usually | resolution |
| --- | --- | --- |
| `mobile/**` | the fork's `translate()` wrapper against an upstream edit to the same line | `git checkout --theirs -- <file>` (take upstream), `git add`; `sync-finish.sh` re-localizes |
| modify/delete | upstream deleted a file the fork edited | if the edit was a fix upstream absorbed, `git rm` it; if it is fork feature, move it to where upstream put that code, then `git rm` the old path |
| `/README.md`, `docs/readme/README.zh-CN.md` | never — `.gitattributes` keeps the fork's | — |
| lockfiles, skill manifests | never — `.gitattributes` keeps upstream's; `sync-finish.sh` regenerates | — |
| `src/renderer/src/i18n/locales/*.json` | never — merged key by key (`config/scripts/merge-locale-catalog.mjs`); `sync-finish.sh` retires translations of keys `en.json` dropped | — |
| anything else | a genuine two-sided change | read both, resolve by hand |

**Anchor a `merge=` pattern that names a basename.** `.gitattributes` matches a
pattern without a slash at every depth, so `README.md merge=keepfork` also kept
the fork's side of `cloud/README.md`, `mobile/README.md` and every other one —
on 2026-09-14 it dropped upstream's new push-gateway section from
`cloud/README.md` without a conflict. It is `/README.md` now.

**The locale catalogues used to be `keepupstream`, and it cost every
translation the fork wrote.** On any two-sided change it took upstream's whole
file; upstream edits `zh.json` most weeks, so the 2026-09-14 sync deleted 603 of
the fork's Chinese entries and 95 English fallbacks for fork-only features, and
the only tell was a lower coverage count. `fork-zh-terminology.mjs` had been
patching the visible half of that since 2026-09-05. The key-by-key driver keeps
both sides' keys; when both translated one key differently the fork's wins, and
English follows upstream's code. One case it cannot see from inside a
translation file — a key upstream never translated, the fork did, and upstream
then retired from `en.json` — so `sync-finish.sh` prunes those against the merged
English afterwards.

**A cluster resolves as one revision.** The fork's cherry-pick era left
half-landed versions of upstream features — #17517's image attachments spans
nine files across `editor/` and `native-chat/`. Taking upstream's side for the
files that happen to conflict, while the ones that auto-merged keep the fork's
older shape, produces a tree where a hook's caller and its callee disagree.
When a conflict turns out to be an intermediate revision, find every sibling
that moved with it — `git diff --numstat refs/sync/mirror HEAD -- <dir>` — and
take upstream's for all of them.

**Patch hashes travel with the patches.** `pnpm` records a sha256 of every file
in `patchedDependencies`; upstream changing what a patch does leaves the
lockfile disagreeing with the tree, and `--frozen-lockfile` refuses it.
`sync-finish.sh` recomputes them. It does not re-resolve: resolution fails for
reasons unrelated to the sync — on 2026-09-03 `sherpa-onnx-darwin-x64@1.12.37`
had been unpublished from npm, so `minimumReleaseAge` could not evaluate it and
rejected the lockfile outright. `main` never saw it because pnpm skips
verification when the lockfile has not changed.

The second, 2026-09-03, crossed 120: 29 files conflicted, 8 taken by rule
(everything the fork had deleted on purpose), 10 more were one cluster
resolved as a unit, and 11 were read individually — every one of those a
two-sided change where upstream reworked a mechanism and the fork owned an
identity value inside it. The mirror extension took seconds.

The first real sync on this model, 2026-09-02, crossed 86 upstream commits:
10 files conflicted, 4 taken by rule (the lockfile driver, a fork-deleted
asset, two files upstream deleted that the fork had only localized or
re-commented), 6 read and resolved (two CI scripts the fork extends, a docs
section the fork owns, a styles file git correctly matched to the fork's
rename, two tests where upstream's version was simply newer). The repair
afterwards was 19 files, every one either a brand seam the rule now covers
or an upstream pin re-based to the fork's bytes. The mirror extension took
seconds.

After the merge commit, run `python3 .claude/skills/upstream-sync/fix-renamed-paths.py`.
The mirror renames upstream's new `orcad-*` files but a reference to a module that has
no Manta twin yet keeps the old spelling — 933 imports, mocks, script and workflow
paths on 2026-10-08. The script rewrites a path only when the old one does not exist
and the Manta one does, so it is safe to rerun.

After the merge, **read what the mirror declined** (`build-mirror.py` prints
the top of it; `sweep-brand.py refs/sync/base` lists it for the tree). A
brand-bearing name upstream introduced this sync that neither rule could
decide — a new env var, a new CamelCase family — stays upstream-spelled until
a fork commit renames it; from then on the mirror follows that decision. Most
of the list is fixture strings that should stay as upstream wrote them.

`sync-finish.sh` refolds the lockfiles, runs the mobile localizer over what
upstream added and fills `zh.json` from the translation memory
(`mobile/src/i18n/translation-memory.zh.json`, keyed by English text — a
string upstream moved keeps its translation), prints what still needs a
human translation, records the new `refs/sync/base`, commits the
regeneration, and runs `sync-verify.sh`.

## Verifying

```bash
.claude/skills/upstream-sync/sync-verify.sh refs/sync/base
```

One command, seven steps, in the only order that works, exiting non-zero on
the first thing wrong. `sync-finish.sh` runs it; run it again after every
repair. Each step is there because skipping it once let something through:

1. **Brand sweep, report only.** The mirror already speaks Manta; what this
   finds is a fork file that lost its spelling. Read the list; apply by hand.
2. **Resurrection audit** — files upstream deleted anywhere in the mirror's
   history that are still in the tree. A modify/delete resolved the wrong way.
3. **Twin audit** — `orca-X` beside `manta-X` is a rename that landed as a copy.
4. **Regenerate** the skill manifest and mobile localization, and check every
   `en.json` key has a `zh.json` entry.
5. **Root gates, every one.** `pnpm lint` is nineteen `&&`-chained commands, so
   the script runs them one by one — chained, the first failure hides the rest.
   One local-only difference is tolerated: CI runs the native import-cycle
   check *before* installing mobile deps, so `mobile/tsconfig.json`'s `extends`
   does not resolve there and no mobile import is followed. Locally it is, and
   upstream's own mobile cycles (two on 2026-09-28) show up; the script reports
   those as a warning, not a failure.
6. **Mobile gates, separately.** `mobile/` has its own oxlint, oxfmt config and
   lockfile; the root commands touch none of them. `--frozen-lockfile` is the
   point — plain `pnpm install` rewrites the lockfile and hides that it was
   upstream's.
7. **Root tests.** Re-run any failure serially before believing it: the
   `.electron` tests launch real Electron and time out at 32s under parallel
   load. `browser-route-tcp-egress` fails on any machine whose DNS answers
   `remote-browser.test`.
   Also local-only: `tests/e2e/relay-region-*.unit.test.ts` and
   `tests/e2e/cross-version-wire/**` (`ci-unit-files.mjs` excludes both), and
   the `mobile-web-app-*-render` tests until `pnpm exec playwright install
   chromium-headless-shell webkit` has fetched the browsers upstream's
   Playwright bump asks for.

**Files the merge takes wholesale lose the fork's edits inside them.** On
2026-09-28 three were caught only by tests: `mobile/rpc-foundation/pilot-scenarios.json`
(the fork's notification scenarios), the tasks and session-route parity pins,
and `CustomKeyModal.tsx` (back to inline English catalogs). For a fork-edited
file upstream also touched, diff the fork's side against the old base
(`git log refs/sync/mirror --grep "Mirror-Of: <old upstream>"`) and replay just
those hunks. Recording goldens are then re-recorded with
`RPC_FOUNDATION_MODE=--record RPC_FOUNDATION_RECORD=1`, and the content diff —
not the header digests — is what to read: resolve each golden's value pool
and compare, because pool keys move whenever content does.

**A KEEP entry is a decision the rule cannot make twice.** `orca-cli` is on
the keep list because it is a backwards-compatible skill alias — renaming it
makes installed skills unresolvable. But the same string appears in a stub CLI
inside `electron-builder-runtime-resources.test.mjs`, where it stands for the
skill the packaged build must list, and there it has to say `manta-cli`. No
rule distinguishes those; only a test does. When a KEEP entry turns up in a
fixture, read what it stands for in that spot.

That one also shows why `pnpm test` on this machine is not the whole gate:
the packaged-runtime probes skip on a cross-arch slice, so on an arm64 Mac the
stub is never executed and the test passes for a reason CI does not share.
Flip `arch:` in the case to the host's to reproduce a CI-only failure locally.

**What the script cannot see** — the layer where identity is a machine-readable
key rather than a word: `Symbol.for` slots, `localStorage`/`AsyncStorage` keys,
HTTP header names, on-disk file names. `tsc` does not check them and the
evidence rule needs a Manta twin that a key nobody tests never has. Three are
known and each is a migration decision, not a rename: `orca.web.onboarding.v1`
/ `orca.web.githubCache.v1` in `src/renderer/src/web/preload-api/web-storage.ts`;
`orca.mobile.connection-log.v1.` in `mobile/src/transport/persisted-connection-log-store.ts`;
`MANTAD_STATE_SNAPSHOT_DIR = 'orcad-state-snapshots'` under `.manta-remote/`.

## Releasing

A sync that lands and never ships is upstream's fixes sitting in a branch. The
fork was three upstream releases behind when this step did not exist, so
`sync-finish.sh` now cuts the release itself and the release rides in the sync
PR. **Merging that PR is what publishes** — `auto-release.yml` tags whatever
version arrives on main, and each tag starts its build.

```bash
node config/scripts/cut-fork-release.mjs --dry-run   # what it would cut
```

It reads upstream's newest **stable** release — their line is what this fork's
version follows, so upstream at `1.4.196` means this fork ships `1.4.196-rc.N`
once it has merged that work — takes the rc after the highest already cut
(from tags and release subjects, not from `package.json`, which is a working
file and lies after a revert), never moves the base backwards, seals the skill
bundle manifest for the version, drafts release notes and refuses to proceed if
they carry a personal identifier. It stops at the commit: main requires `verify`
and `Mobile Checks`, so tagging happens on arrival, which is what makes every
tag point at a commit those checks passed.

Mobile moves in the same commit when upstream's newest `mobile-android-v*` is
ahead of `mobile/app.json`. Both platforms read that one marketing version, and
`prepare-android-release.mjs` rejects a tag that disagrees with the committed
one, so the bump has to be committed rather than passed at release time.

**Read the drafted notes and trim them.** The draft groups upstream's commits by
scope into a handful of bullets; it is built only from commits carrying the
mirror's `Mirror-Of:` trailer, because without that split the fork's own sync
plumbing gets announced as release news. A release note is a title, a sentence,
and three to five bullets — rationale and implementation live in the commits.

Full picture, including the one credential the automation needs:
[`docs/reference/fork-release-automation.md`](../../../docs/reference/fork-release-automation.md).

## Landing it

Open a pull request; merge without squash. Nothing in CI runs on a push to
`main` except Mobile Checks, and a red check does not block a merge — the
2026-08-30 sync merged with 28 mobile type errors visible in CI. Read the
checks. `cross-version wire compatibility` needs an upstream release tag the
fork's remote does not carry and will stay red until that is decided.

`verify` is required and fails when that job's runtime-launcher ratchet sees a
daemon protocol bump and a launcher change in one PR. A sync spanning several
upstream releases always carries both, so label the PR
`allow-runtime-launcher-protocol-bump` before its last push — the gate reads
labels only from a push event, never a re-run.

Two things the sync itself will not tell you:

- **The version follows upstream's line.** Read their newest tag, not
  `package.json` on their main.
- **Seal the skill bundle manifest** for the release with
  `node config/scripts/generate-skill-bundle-manifest.mjs --release <version>`.

## The tools

All of them import one rule, `brand_rule.py`:

- **IDENTITY** — values that are not a word swap: `com.stablyai.orca →
  cn.sh.manta`, `onorca.dev → manta.sh.cn`. Verified against upstream's tree.
- **EVIDENCE** — a brand token is renamed only if the fork already uses its
  Manta form as a whole word. That keeps the deliberate remnants without
  enumerating most of them, because none has a Manta twin.
- **FAMILY** — second tier, for the mirror only: a file upstream adds this
  week has no Manta twin yet, but if the fork has forty `manta-runtime-*`
  files, `orca-runtime-bind-pty-incarnation-handle` is decided. A prefix that
  carries the brand plus at least one more segment (`manta-runtime`,
  `MantaRuntime`, never the bare word) counts. Never for a dotted key without
  a file extension (a storage slot — renaming one strands data), a token
  ending in `-`/`_` (a mkdtemp prefix), or a `/tmp` path. On the replayed
  sync it covered 42% of what the direct rule declined, at 100% precision on
  a sample.
- **SEGMENT** — a relative import (`../main/orcad/x`) never matches a
  repository-relative family, but `mantad` being a directory here decides it.
  Any path segment whose Manta form is a file or directory name the fork has
  counts. Missed once: three typecheck errors and twenty test files that
  could not load.
- **DOTTED** — a token with two or more dots and no slash is a key, judged
  segment by segment: `remote.<name>.orca-created` renames its last segment
  because `manta-created` is what the desktop reads, while `orca.host.x`
  stays because a bare brand segment proves nothing. One dot and a short
  extension is a filename (`orca-installer-hooks.nsh`), never a key.
- **KEEP** — the few that do and must still stay: `stablyai/orca` (guards the
  workflows this fork must never run), the skill aliases, `/usr/bin/orca` and
  the phrase `GNOME Orca` (Ubuntu's screen reader — the reason the Linux binary
  is `manta-ide`), the App Store URL. **KEEP_PATH** — files that are *about*
  upstream, or where Orca is the whale, or that describe infrastructure only
  upstream runs. The mirror honours it for both the path and the bytes, so a
  kept file arrives exactly as upstream wrote it; the blob cache is keyed by
  `(sha, kept)` because one tree can hold the same bytes at a kept path and an
  ordinary one, and those want opposite answers.

Before this module there were two copies with different rules, and the
conflict-time one renamed blindly with an identity map pointing at a bundle id
upstream never used. That is where "GNOME Manta screen reader" and
`com.stablyai.manta` came from.

**`build-mirror.py`** extends the mirror from its tip — the upstream commit named
by the tip's `Mirror-Of:` — not from a prefix counted at upstream's root. The
mirror starts partway through upstream's history (4cb013c0), and on 2026-09-28
fetching an old upstream tag brought the earlier history into the clone: the
root-prefix match then found nothing and would have rebuilt all 11,986 commits
onto a lineage main shares nothing with. Replayed against a grafted, truncated
history the tip-based extension produced byte-identical commits. Only when the
tip is not in upstream's history (a rewrite) does it fall back to the prefix.
It streams upstream's new commits through `git fast-import`
on top of the mirror it finds, referencing unchanged blobs by SHA and emitting
only transformed ones. Blobs the mirror already carries keep their names — an
unchanged file is referenced, not re-decided under newer evidence. Evidence
is read once with a single ripgrep pass over a checkout of the fork — `git grep
-f` with the same patterns is superlinear, 500 took 83 seconds — with patterns
longest-first, because ripgrep's alternation is leftmost-first and a short
pattern shadows every longer one it prefixes. 387 commits in eight minutes.
`--report` prints how much of the fork the mirror reproduces; expect ≥95%.

**`sync-bootstrap.sh`** is the one-time move onto the mirror: the fork's tree
over the mirror's, dropping only what the fork's history deleted on purpose
and code files nothing imports (upstream's parallel splits of components the
fork had already replaced — found by resolving imports, since a basename
match cannot tell `../src/pair-scan-styles` from `../src/theme/pair-scan-styles`).
It edits no content; a bootstrap that also cleans up cannot be checked against
the fork it came from.

**`sync-selftest.sh`** replays a sync the fork already absorbed by hand and
diffs the outcome against it; run it after changing any tool. Replaying this
week's — 371 upstream commits — as a merge: 40 files conflicted, 16 resolved
by rule, 24 for a person, of which two more go to rules once `.gitattributes`
is in the base and the rest are relay hooks and skill prose upstream also
edited. The cherry-pick path had produced 372 blind-rebranded picks, a 92-file
repair commit and 24 failing tests for the same range.
**`sweep-brand.py`** and **`rebrand-merge.py`** remain for reading and for
the old cherry-pick path; neither is part of the sync now.

## What upstream owns

`cloud/`, the 26 `.github/workflows/cloud-*.yml`, and
`.github/actions/cloud-sql-rollout-lease/` are upstream's hosted relay fleet and
the GCP estate that runs it — their projects, their service accounts, their
numeric repository ids. This fork operates none of it, and its own relay is
`relay-server/`. It is not import-free, though: root unit tests
(`tests/e2e/relay-region-*.unit.test.ts`) load `cloud/apps/relay` source, and
`unit-tests.yml` installs its deps with `--filter '@orca-cloud/relay...'`. That
scope, like the push proof domain separators signed against it, is on
KEEP_SUBSTRING: renamed, the filter matched nothing and CI could not find `pg`.

They are on KEEP_PATH, so they track upstream byte for byte. Renaming inside
them produced names that were neither upstream's nor this fork's and existed
nowhere — `stablyai/manta` beside upstream's real repository id, a Cloud Run
service pushed past the platform's own 46-character service-plus-tag bound, a
MIG-name validator still spelling `orca-` while its fixtures had moved. None of
it could fail visibly, because `Cloud Verify` only runs when `cloud/**` changes;
it had never once passed here.

## What this fork owns

Upstream must never overwrite these. If a conflict touches one, stop and think:

- `relay-server/` and everything about the self-hosted relay
- `mobile/src/i18n/` and the `translate()` wrappers throughout `mobile/`
- `.github/workflows/fork-release.yml` and the fork's contract tests
- the three dev-channel mac workflows, whose job guards point at
  `stablyai/orca` on purpose so this fork never runs them
- `README.md`, `docs/readme/README.zh-CN.md`

## Moving `main` onto the mirror (once)

`sync/mirror-bootstrap` is `main`'s content on the mirror's history. To make
it `main`:

```bash
.claude/skills/upstream-sync/sync-cutover.sh     # asks before it does anything
```

It keeps the old `main` as `main-legacy`, lifts the force-push block for one
push and restores it, and publishes the sync refs. `main` is protected:
`verify` and `Mobile Checks` must pass before a merge.

Every open branch based on the old `main` must be rebased onto the new one
(`git rebase --onto main main-legacy <branch>`) — the trees match, so that is
mechanical. Publish the sync refs so a fresh clone can pick up where this one
left off: `git push origin refs/sync/base refs/sync/mirror`. `sync-run.sh`
fetches them from origin before it starts, and `sync-finish.sh` says when to
push them again.

**Forgetting that push used to be destructive.** `sync-run.sh` force-fetched
origin's `refs/sync/*` over the local ones. The 2026-09-09 sync never pushed
them, so on 2026-09-14 a correct local base (`2fd8efbcac`) was replaced by a
stale one, the mirror was extended from the wrong commit into a second lineage
for work `main` already had, and the merge came back with 418 conflicts — 127 of
them add/add — that were the previous sync over again. Resolving them would
have merged the same upstream changes twice. It now takes origin's refs only
when they are ahead of the local ones, treats the second parent of `main`'s
latest `sync: merge upstream` commit as the base that cannot go stale, and
refuses to merge when `main` and the mirror meet before the base.

## How it got here

Until 2026-09-02 a sync matched upstream commits by subject and cherry-picked
the difference, with a blind rebrand at conflict time and a manual sweep after.
Every sync ended with a repair commit of a few hundred files — 344, 324, 380,
92 — because the rename was stored as 6,100 files of history and replayed
against every pick. Half-renames, resurrected deletions, un-localized upstream
features and a release workflow left on the wrong pnpm were all one week's
fallout. The census above is what made the mirror the obvious shape.

• SKILL.md 24 KB
• brand_rule.py 19 KB
• build-mirror.py 16 KB
• fix-renamed-paths.py 3 KB
• orphan-imports.py 2 KB
• rebrand-merge.py 10 KB
• refresh-patch-hashes.mjs 3 KB
• sweep-brand.py 3 KB
• sync-bootstrap.sh 4 KB
• sync-cutover.sh 2 KB
• sync-finish.sh 3 KB
• sync-i18n.py 3 KB
• sync-run.sh 7 KB
• sync-selftest.sh 5 KB
• sync-verify.sh 8 KB