[upstream #24922] fix: keep unread workspace cue visible while working

.gitattributes

@@ -1,12 +1,90 @@
-/config/scripts/create-draft-release.mjs text eol=lf
-/config/scripts/orca-dev.mjs text eol=lf
-/config/scripts/latest-stable-release.mjs text eol=lf
-/config/scripts/publish-complete-draft-releases.mjs text eol=lf
-/config/scripts/release-rc-history.mjs text eol=lf
-/config/scripts/run-internal-dev-setup.mjs text eol=lf
-/config/scripts/verify-cli-bin.mjs text eol=lf
-/config/scripts/verify-release-required-assets.mjs text eol=lf
+# A shebang plus CRLF makes vite's SSR transform emit a literal `#!` mid-module,
+# so any suite importing the script dies at load with a SyntaxError. Pin the whole
+# directory rather than the scripts that happen to have a test today.
+/config/scripts/**/*.mjs text eol=lf
 /skill-guides/*.md text eol=lf
 /skill-stubs/*.md text eol=lf
+/skill-stubs/_shared/*.md text eol=lf
 /skills/*/SKILL.md text eol=lf
 /src/cli/bundled-skill-guides.ts text eol=lf
+# Bundled plugin trees are byte-hashed; CRLF checkout would break the pinned hash.
+/resources/plugins/** text eol=lf
+# Relay assets are copied verbatim into the bundle and hashed byte-for-byte into
+# .version, which names the immutable remote install dir. A CRLF checkout makes a
+# Windows-built client disagree with a mac/Linux-built one on the same release,
+# so one host ends up with two relay trees (#17886 review).
+/config/relay-assets/** text eol=lf
+# Pin the bytes so a patch reads and diffs identically on every host. It is NOT
+# what makes the hash right: pnpm hashes a patch LF-normalized, so a CRLF checkout
+# cannot change it. Believing otherwise put a hand-computed raw digest in the
+# lockfile twice and broke every install (#17886).
+# These files are stored LF, which is not always the encoding they were written
+# against -- @vscode/windows-process-tree ships CRLF sources -- so any code that
+# runs `git apply` on one must force `-c core.autocrlf=input` rather than trust
+# the host's setting. See config/scripts/windows-process-tree-gyp-rebuild.mjs.
+/config/patches/*.patch -text
+# Same reason, and pnpm parses these too: a CRLF checkout makes the mobile
+# patches unparseable, so Windows packaging dies on ERR_PNPM_INVALID_PATCH.
+/mobile/patches/*.patch -text
+# The xterm bundle hunks also make a diff nobody can read; review the hand-written
+# source patch under xterm-src/ instead. The sibling patches stay diffable.
+/config/patches/@xterm__xterm@*.patch -diff
+/config/patches/xterm-src/*.patch text eol=lf
+# pnpm parses these unified diffs during Windows installs; keep checkout bytes stable.
+/mobile/patches/*.patch -text
+# Generated wrapper fixtures: collapse them in the PR diff so they stop drowning
+# the reviewable change, and pin LF because they are compared byte-for-byte.
+# Not -diff: the shell diff is the review surface when a wrapper does change.
+/src/main/__fixtures__/shell-wrapper-snapshots/*.txt linguist-generated=true text eol=lf
+# Captured agent PTY transcripts. -text, not `text eol=lf` like the wrapper snapshots above:
+# these carry real CR and CRLF bytes as the terminal emitted them, and line-ending
+# normalisation on a Windows checkout would rewrite the evidence the fixture exists to be.
+/src/main/runtime/__fixtures__/*.txt -text
+/src/main/daemon/__fixtures__/pty-transcripts/*.txt -text
+# Generated runtime English subset: compared byte-for-byte by
+# verify:localization-runtime-catalog, so a CRLF checkout would fail the gate.
+/src/renderer/src/i18n/en-runtime-required.json linguist-generated=true text eol=lf
+# Generated method->params catalog: compared byte-for-byte by
+# verify:rpc-params-catalog, so a CRLF checkout would fail the gate.
+/src/shared/rpc-contract/rpc-params-catalog.generated.ts linguist-generated=true text eol=lf
+# Mobile RPC recording goldens: replay requires the file text to equal what rpc:record writes
+# (LF), so a CRLF checkout would fail every golden.
+/mobile/rpc-foundation/goldens/*.json text eol=lf
+# Mobile web page source. Every text byte here is hashed into an asset digest and from
+# there into buildId, so a CRLF Windows checkout would ship a different bundle id for
+# identical source (91af2897 vs 9d78435e, measured on the bundle this replaced).
+/mobile/src/** text eol=lf
+/mobile/app/** text eol=lf
+/mobile/web-entry/** text eol=lf
+# The blanket pin above would mark a future binary as text; exempt the asset types an
+# RN page actually carries.
+/mobile/src/**/*.png -text
+/mobile/src/**/*.jpg -text
+/mobile/src/**/*.jpeg -text
+/mobile/src/**/*.gif -text
+/mobile/src/**/*.ico -text
+/mobile/src/**/*.webp -text
+/mobile/src/**/*.ttf -text
+/mobile/src/**/*.otf -text
+/mobile/src/**/*.woff -text
+/mobile/src/**/*.woff2 -text
+/mobile/app/**/*.png -text
+/mobile/app/**/*.jpg -text
+/mobile/app/**/*.jpeg -text
+/mobile/app/**/*.gif -text
+/mobile/app/**/*.ico -text
+/mobile/app/**/*.webp -text
+/mobile/app/**/*.ttf -text
+/mobile/app/**/*.otf -text
+/mobile/app/**/*.woff -text
+/mobile/app/**/*.woff2 -text
+/mobile/web-entry/**/*.png -text
+/mobile/web-entry/**/*.jpg -text
+/mobile/web-entry/**/*.jpeg -text
+/mobile/web-entry/**/*.gif -text
+/mobile/web-entry/**/*.ico -text
+/mobile/web-entry/**/*.webp -text
+/mobile/web-entry/**/*.ttf -text
+/mobile/web-entry/**/*.otf -text
+/mobile/web-entry/**/*.woff -text
+/mobile/web-entry/**/*.woff2 -text

.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Product source remains owned by its normal reviewers; localization inputs need focused review.
+/src/renderer/src/i18n/locales/ @brennanb2025
+/config/scripts/*localization*.mjs @brennanb2025
+/config/scripts/*locale*.mjs @brennanb2025
+/config/i18next.config.ts @brennanb2025
+
+# The relay's deploy and operate surface: workspace, workflows, and the rollout lease action.
+/cloud/ @Jinwoo-H
+/.github/workflows/cloud-*.yml @Jinwoo-H
+/.github/actions/cloud-sql-rollout-lease/ @Jinwoo-H

.github/CONTRIBUTING.md

@@ -21,6 +21,11 @@ pnpm install
 pnpm dev
 ```
 
+Ordinary installs include native optional dependencies for the current OS and CPU only.
+Before a cross-architecture build (including `pnpm build:mac`, which produces both x64 and
+arm64 artifacts by default), run `pnpm install:release` to add the other CPU's variants.
+See [the install policy](../docs/reference/pnpm-install-policy.md).
+
 ## Branch Naming
 
 Use a clear, descriptive branch name that reflects the change.
@@ -52,21 +57,19 @@ If your change affects UI or interaction behavior, verify it on the platforms it
 
 Project-owned type declarations belong in `.ts` files. `.d.ts` is reserved for ambient shims (e.g., `env.d.ts`, `vite/client.d.ts`). TypeScript's `skipLibCheck: true` setting applies globally, including to our own `.d.ts` files, which means any unresolved type reference in a `.d.ts` silently becomes `any` at its call sites. Write your types in `.ts` files so the compiler actually checks them.
 
-CI enforces this for `src/preload/` and `src/shared/` — see `docs/preload-typecheck-hole.md`.
+CI enforces this for `src/preload/` and `src/shared/`.
 
 ## Pull Requests
 
-Each pull request should:
+Each pull request should follow [`.github/pull_request_template.md`](./pull_request_template.md). In particular:
 
-- explain the user-visible change
-- stay focused on a single topic when possible
-- include screenshots or screen recordings for new UI or behavior changes
+- open with an ELI5 of the change (plain language paragraph; the PR title is the one-liner)
+- explain what changed and why, and stay focused on a single topic when possible
+- for any UI or interaction change, attach **before and after** screenshots (or short videos); if there is no visual change, say `No visual change` and why
 - include high-quality tests when behavior changes or bug fixes warrant them
 - include a brief code review summary from your AI coding agent that explicitly checks cross-platform compatibility, SSH/remote/local compatibility, supported agent and integration compatibility, performance risk, UI quality when applicable, and basic security risk
 - mention any platform-specific, remote/SSH-specific, agent-specific, integration-specific, or git-provider-specific behavior and testing notes
-- **Include your X (Twitter) handle!** We love giving shoutouts to our contributors when we merge features on [@orca_build](https://x.com/orca_build).
-
-If there is no visual change, say that explicitly in the PR description.
+- **Include your X (Twitter) handle** in the PR template Author section — we shout out contributors when we merge features on [@orca_build](https://x.com/orca_build).
 
 ## Release Process
 
@@ -114,7 +117,6 @@ All stable kinds (`patch`, `minor`, `major`) are computed off the latest _stable
 
 The scheduled 2x/day RC cron in [`release-rc.yml`](../../actions/workflows/release-rc.yml) is independent and continues to run automatically from `main`.
 
-
 ## Release Channels
 
 The public Homebrew cask tracks stable desktop releases:

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -10,6 +10,8 @@ body:
       value: |
         Use this form for Orca bugs. Include enough detail for someone else to reproduce the issue.
 
+        Please write your issue in English.
+
   - type: dropdown
     id: os
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -10,6 +10,8 @@ body:
       value: |
         Use this form for new features or workflow improvements.
 
+        Please write your issue in English.
+
   - type: textarea
     id: problem
     attributes:

.github/ISSUE_TEMPLATE/other.yml

@@ -2,6 +2,11 @@ name: Other
 description: Report another Orca issue type
 title: '[Other]: '
 body:
+  - type: markdown
+    attributes:
+      value: |
+        Please write your issue in English.
+
   - type: textarea
     id: details
     attributes:

.github/actions/cloud-sql-rollout-lease/README.md

@@ -0,0 +1,152 @@
+# Cloud SQL rollout lease
+
+A compare-and-swap lease on one Cloud Storage object, used to serialize Cloud SQL
+**connection-budget** rollouts across two repositories.
+
+`concurrency.group: production-cloud-sql-rollout` only serializes runs inside a single repository.
+Once the relay workflows live in `stablyai/orca` and the app workflows stay in
+`stablyai/orca-cloud`, there are two independent queues pointed at one shared Cloud SQL instance.
+`relay-cloud-sql-connection-budget.mjs` computes `rolloutOverlap` as a `Math.max` over the relay
+director, api, auth and relay-cell candidates, which is only sound when exactly one rollout is in
+flight. This lease is what keeps that assumption true. Keep the per-repo concurrency groups **and**
+the lease; they solve different halves of the problem.
+
+## What it protects
+
+No workflow runs a Cloud SQL schema migration. Every locked workflow either deploys a Cloud Run
+revision or applies a GCE instance template against the shared instance, so the lease must cover
+**all rollouts**, not just migrations.
+
+## Usage
+
+The lease step must run **after** `google-github-actions/setup-gcloud`, and after
+`actions/checkout` — `uses: ./.github/actions/...` resolves against the checked-out workspace.
+It belongs in the first job of the workflow that holds a GCP credential, which is not always the
+gate job: `deploy-relay-production-same-cap`'s gate runs no `gcloud`, so its first acquire happens
+in the first cell job.
+
+```yaml
+- uses: google-github-actions/auth@v2
+    with: { workload_identity_provider: ..., service_account: ... }
+- uses: google-github-actions/setup-gcloud@v2
+- uses: ./.github/actions/cloud-sql-rollout-lease
+  with:
+    bucket: onorca-cloud-terraform-state
+    object: terraform/state/cloud-sql-rollout/production.lock
+```
+
+Buckets and objects in use:
+
+| Environment | Bucket                                 | Object                                              |
+| ----------- | -------------------------------------- | --------------------------------------------------- |
+| production  | `onorca-cloud-terraform-state`         | `terraform/state/cloud-sql-rollout/production.lock` |
+| staging     | `onorca-cloud-staging-terraform-state` | `terraform/state/cloud-sql-rollout/staging.lock`    |
+
+Workflows that serve both environments (`deploy-relay-asia-topology`,
+`operate-relay-asia-admission`) select the pair with an `inputs.environment == 'production'`
+ternary on both `bucket` and `object`. `deploy-staging` keeps its own `deploy-artifacts-staging`
+concurrency group but takes the staging lease, because it rolls the staging API revision.
+
+The object sits beside `terraform/state/relay-fence-broker/<env>.lock`. The IAM grant names both the
+relay and app service accounts, so it is a **foundation-root** resource: `roles/storage.objectAdmin`
+conditioned on the `terraform/state/cloud-sql-rollout/` prefix, **plus** an unconditioned
+`roles/storage.legacyBucketReader`. Without the second role the generation-matched write fails in a
+way that looks like a permissions flake.
+
+## One lease per run, not per job
+
+`deploy-relay-production-capacity` calls its reusable job six times and
+`deploy-relay-production-same-cap` four times. Each call is a separate job on a separate runner, so
+a naive per-job acquire/release would leave the object free between waves — for runs that have taken
+up to 85 minutes.
+
+The lease is therefore keyed to the **run**, not the job. `holder-key` defaults to
+`${{ github.repository }}/${{ github.run_id }}`, and a job that finds its own holder key on a live
+lease **re-enters** it: the record is refreshed, not rejected. Every job in the chain acquires; only
+the last one releases.
+
+```yaml
+jobs:
+  gate:
+    steps:
+      - uses: ./.github/actions/cloud-sql-rollout-lease
+        with: { bucket: ..., object: ..., release: 'false' } # intermediate
+
+  wave-1: # ... release: 'false' on every wave job
+
+  release_lease:
+    needs: [gate, wave-1, wave-2, wave-3, wave-4]
+    if: always()
+    steps:
+      - uses: google-github-actions/auth@v2
+      - uses: google-github-actions/setup-gcloud@v2
+      - uses: ./.github/actions/cloud-sql-rollout-lease
+        with: { bucket: ..., object: ..., release: 'true' } # final
+```
+
+`release: 'false'` still acquires and still runs its `post` step; `post` only skips the delete. A
+single-job workflow leaves `release` at its `true` default and needs no extra job. So does a
+workflow whose several jobs can never hold the lease at once: `prove-relay-staging-capacity`'s two
+lease-holding jobs are guarded by complementary `inputs.mode` conditions, and the contract test
+checks that exclusivity rather than assuming it.
+
+If the final job never runs (runner killed, run cancelled hard), the lease expires on its TTL.
+
+## Timing
+
+- **TTL 35 minutes**, matching `apps/relay-fence-broker/src/mutation-lease.ts`.
+- **Renewal every 5 minutes.** `main` spawns a detached background Node process that rewrites
+  `expires_at` on the same generation-matched path; `post` kills it by pid read back from
+  `$GITHUB_STATE`. The renewer stops on its own the moment the object stops being ours, and has a
+  six-hour backstop in case `post` never runs. Its log is written to
+  `$RUNNER_TEMP/cloud-sql-rollout-lease-renewer.log` and echoed by `post`.
+- Renewal is mandatory, not optional: capacity runs have taken 85 minutes, well past any sane TTL.
+
+## Failure behaviour
+
+| Situation                        | Behaviour                                                                                                         |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Object absent                    | Acquire with `ifGenerationMatch: 0`.                                                                              |
+| Live lease, our own holder key   | Re-enter. Refresh `expires_at`, keep `acquired_at`. Never fails.                                                  |
+| Live lease, another holder       | **Fail the job immediately**, printing the holder's repository, workflow and run URL. Never queues, never steals. |
+| Expired lease                    | Take over with the observed generation and emit `::warning::` naming the stale holder.                            |
+| `412` on write                   | Someone raced us. Fail as a conflict.                                                                             |
+| Bucket unreachable, `403`, `5xx` | **Fail closed.**                                                                                                  |
+| Record present but unparseable   | **Fail closed.** A record we cannot read is never treated as free; an operator must inspect and delete it.        |
+| Release finds a foreign holder   | Warn and leave it alone. Our lease had already expired.                                                           |
+| Release fails                    | Warn only. `post` never fails a job over a release; the TTL bounds the damage.                                    |
+
+## Why `monitor-relay-production` must not use this
+
+`monitor-relay-production` is in the `production-cloud-sql-rollout` concurrency group but is
+**read-only**: its identity holds only monitoring, logging, Cloud SQL and compute _viewer_ roles,
+and it runs `gcloud sql instances describe`, never a mutation. It consumes no connection budget.
+Putting it on the durable lease would let a monitoring run block a real rollout, and a rollout block
+monitoring exactly when an operator most needs it. Keep its same-repo concurrency group; keep it off
+the lease. The lock census contract test records it in the not-a-candidate map with this reason.
+
+## Token acquisition
+
+`gcloud auth print-access-token`, not a hand-rolled exchange of the `external_account` credentials
+file. Every consuming workflow already runs `setup-gcloud`, gcloud already handles every ADC flavour
+including the service-account impersonation leg, and this action must stay zero-dependency because
+it is duplicated by hand into the public repo. The GCE metadata server that
+`apps/relay-fence-broker/src/google-metadata.ts` uses does **not** exist on GitHub or Blacksmith
+runners; only the compare-and-swap algorithm is shared with the fence broker.
+
+## Duplication
+
+This directory is copied verbatim into `stablyai/orca`. It has no `package.json`, no
+`node_modules`, and imports nothing outside itself — `action-contract.test.mjs` enforces all three.
+Cross-repo consumption via `uses: stablyai/orca/.github/actions/...@<sha>` was rejected: it would
+put public-repo code inside private app deploys that hold a production credential, and neither
+repository protects `main` today.
+
+## Tests
+
+```
+node --test .github/actions/cloud-sql-rollout-lease/
+```
+
+`storage-lease.test.mjs` drives the real compare-and-swap path against an in-memory Cloud Storage
+fake that enforces generations. No network.