Merge upstream/dev into feat/tailscale for PR #2270

Rebase Tailscale outbound integration onto current upstream dev:
- Keep Tailscale profile injection in setup action and Tools menu entry
- Adopt upstream desktop lifecycle, Android service refactor, and helper v6
- Update Clash.Meta submodule to upstream dev pointer
- Regenerate Riverpod, Freezed, and l10n outputs after conflict resolution

Co-authored-by: MichaelZ <joei4cm@users.noreply.github.com>

Author: cursoragent

.agents/architecture.md

@@ -274,13 +274,16 @@ Responsibilities are deliberately split:
 - `core/` and `services/helper/` remain source owners; `libclash/` and Android `jniLibs`/header directories are generated
   output locations.
 - `setup.dart` remains the release/package orchestrator and does not pre-build
-  platform artifacts or pass Core integrity data into Dart.
+  platform artifacts or use `dart-define` for Core integrity data. The Windows
+  build tool writes the runtime `manifest.json` beside the Core output, and the
+  Windows bundle copies it beside the application executable.
 
 Platform outputs remain explicit:
 
 - Android builds the Go core as `c-shared`, then copies `libclash.so` and generated headers into the `:core` Android module.
 - macOS and Linux build a standalone `FlClashCore` process used by the desktop socket integration.
-- Windows builds `FlClashCore.exe` plus the Rust `FlClashHelperService.exe` privileged helper.
+- Windows builds `FlClashCore.exe`, the Rust `FlClashHelperService.exe` privileged helper, and a
+  `manifest.json` containing only `coreSha256`.
 
 The hooks follow rust_api/Cargokit's phony-output scheduling pattern, but setup uses its own cache because it builds both a
 Go core and, on Windows, a separate Rust helper. Per-target records live under `.dart_tool/setup_build_cache/v1/`:
@@ -303,11 +306,23 @@ Windows helper integrity/version check:
 
 - The build tool constructs the Core first, calculates its SHA256, and always
   builds the Rust Helper with release hardening and that expected hash.
-- Flutter does not embed or send the Core SHA256. Debug, Profile, and Release
+- Flutter reads the Core SHA256 from the bundled `manifest.json` and sends it with `/ping`. Debug, Profile, and Release
   builds use the same Helper protocol and may use TUN through the same flow.
-- `/ping` is loopback-only and requires no request token. The Helper verifies the fixed `FlClashCore.exe` beside it against
-  its embedded SHA256 before reporting readiness, and repeats verification before every launch. The response includes the
-  running Helper path and protocol header; Dart checks both against the current installation.
+- `/ping` is loopback-only and requires no request token. The Helper compares the requested SHA256 with its embedded value
+  and checks that the fixed `FlClashCore.exe` beside it exists; `/start` performs the actual Core SHA256 verification before
+  every launch. The response includes the running Helper path and protocol header; Dart checks both against the current
+  installation. The launcher selects the Helper only when `/ping` reports ready; any other readiness (missing manifest,
+  unavailable Helper, or a Helper built for a different Core) falls back to the direct Core without requesting elevation.
+  If `/start` reports a pre-spawn failure — `coreVerificationFailed` (the on-disk Core no longer matches the SHA the
+  Helper and manifest agree on) or `processLaunchFailed` (the Core process could not be spawned) — the launcher degrades
+  to the direct Core rather than failing the launch. `/start` releases the previously managed Core before it verifies,
+  so the Helper owns no Core when either code is reported and the direct retry cannot race a Helper-managed Core.
+  A mismatched Helper is reinstalled through the explicit TUN authorization flow, not at startup.
+- TUN is not a required run condition. A direct Core runs unelevated and cannot bring up TUN, so any degrade to the
+  direct Core — an unready Helper at resolve time, or a pre-spawn `/start` failure — silently drops TUN and keeps the
+  Core running. Degrading is preferred over failing the launch: an unverified Core carries no privilege the direct
+  launch path did not already have. `manifestMissing` is the one readiness that is surfaced to the user, because it
+  means the installation itself is incomplete.
 - Flutter creates a 128-bit lowercase-hex session ID and uses it as the random named-pipe suffix. `/start` receives only
   that address and session ID, validates the fixed `FlClashCore_<session>` namespace, starts the fixed Core beside the
   Helper, and returns the same session ID plus the spawned PID. Flutter verifies both the session and named-pipe peer PID.
@@ -350,13 +365,16 @@ The helper owns its Windows Service Control Manager lifecycle through two elevat
 The Dart layer only launches the helper's `install` command through `ShellExecuteW`; it does not compose `sc.exe`,
 `taskkill`, or `cmd.exe` command lines.
 
-In every Flutter build mode it opens the fixed Core executable beside the Helper without write/delete sharing, validates
-it against the SHA256 embedded only in the Helper, and keeps that handle open through process creation. Protocol version 5
-uses 32-character lowercase-hex session ownership:
+In every Flutter build mode `/start` opens the fixed Core executable beside the Helper without write/delete sharing,
+validates it against the SHA256 embedded only in the Helper, and keeps that handle open through process creation.
+`/ping` only compares the requested `coreSha256` with the Helper's embedded value and checks the fixed Core path exists;
+it never hashes the Core. Protocol version 6 uses 32-character lowercase-hex session ownership:
 
-- `GET /ping` verifies Core and returns the current Helper executable path with `x-flclash-helper-protocol`.
-- `POST /start` rejects unknown JSON fields, validates `{address, sessionId}`, replaces any previously managed Core, and
-  returns `{sessionId, pid}`.
+- `GET /ping?coreSha256=...` returns the current Helper executable path with `x-flclash-helper-protocol` when the
+  requested SHA matches.
+- `POST /start` rejects unknown JSON fields, validates `{address, sessionId}`, then releases any previously managed Core
+  before verifying the Core — so every outcome, including a rejected one, leaves the Helper owning no Core — and returns
+  `{sessionId, pid}`.
 - `POST /stop` validates `{sessionId}` and only stops the matching managed Core. A session mismatch is HTTP 409.
 - `GET /logs` exposes the bounded recent Helper/Core stderr buffer with `no-store` caching.
 

.agents/commands.md

@@ -40,16 +40,7 @@ The Makefile wraps `plugins/setup/buildkit/run_build_tool.sh`; prefer the `make`
 
 ## Flutter Development
 
-The project follows FVM's `stable` channel locally. Release CI pins an exact
-Flutter version separately; see `.agents/project.md`.
-
-```bash
-fvm flutter pub get
-fvm flutter run
-fvm flutter test
-```
-
-Plain Flutter also works when the global SDK matches project constraints:
+Use the default Flutter SDK directly:
 
 ```bash
 flutter pub get

.agents/project.md

@@ -4,9 +4,7 @@ FlClash is a multi-platform proxy client based on ClashMeta (mihomo), built with
 
 ## Version Notes
 
-- `.fvmrc` follows the FVM `stable` channel for local development; it does not
-  pin an immutable Flutter version.
-- Release CI pins Flutter 3.44.4. Local `stable` may diverge, so trust the CI
+- Release CI pins Flutter 3.44.4. Local SDK may diverge, so trust the CI
   version as the source of truth for release builds.
 - Dart SDK constraint: `>=3.8.0 <4.0.0`.
 

.agents/rules.md

@@ -21,6 +21,46 @@ Generated directories are excluded from analysis:
 - `lib/**/generated/**`
 - `plugins/**`
 
+## Comments
+
+Comments are opt-in and reserved for the few places that genuinely need one. Density is the point: every comment that
+restates the code devalues the comments that carry real information, until readers skim past all of them. A file with
+three comments that matter is more readable than one with thirty.
+
+### Writing Comments
+
+- Never add a comment on your own initiative. This covers explanatory, narrative, TODO, section-divider, and
+  documentation comments, in Dart, Kotlin, Swift, Go, Rust, YAML, Gradle, and any other file you touch.
+- Never annotate line by line or statement by statement, and never restate in prose what the code already says. If a
+  block needs a comment per step, the block needs better names or a smaller decomposition instead.
+- When a change genuinely cannot be understood without a comment, do not write it silently. Explain what is unclear,
+  propose the exact comment text, and wait for the user to approve it before adding it.
+- Delete commented-out code, stale version notes, and comments that only restate the code, whenever you edit the file
+  that contains them. This does not need approval.
+- These are not comments and must be preserved: analyzer and linter directives (`// ignore:`, `// ignore_for_file:`,
+  `// coverage:ignore`), license and copyright headers, code-generation markers, and comments inside vendored upstream
+  code such as `lib/widgets/open_container.dart`.
+
+### Where Knowledge Belongs
+
+Pick the destination by where the constraint would be violated, not by how important it feels.
+
+- **Assertable behavior goes in a test.** A test is the only form that cannot drift, because it fails when the behavior
+  it describes is broken. Prefer it over both a comment and a document whenever the fact can be checked in code.
+- **Repository-wide defaults, ownership, and invariants go in `.agents/*.md` or a `.agents/skills/*/SKILL.md`.** They
+  are violated from many files, so they must reach every future agent at session start. A comment in one file cannot do
+  that.
+- **A fact that is true only at one call site, and is not visible from that call site, stays a comment there.** Its
+  value is being in the reader's line of sight at the moment of the edit. `lib/common/constant.dart` is the model case:
+  the delay-test concurrency cap is bound to `mBatch` in `core/common.go`, and whoever changes that number must see the
+  constraint on the same screen.
+
+Both failure directions are real. Moving a local constraint into `.agents/` hides it from the person editing the line;
+leaving a repo-wide policy as a comment reaches only the reader of that one file.
+
+Before any of the three, prefer encoding the intent in structure and naming — a named mixin, type, or method that makes
+the invariant hard to break beats prose that asks the next reader not to break it.
+
 ## Core API Safety
 
 - Do not expose direct filesystem deletion APIs through Core or helper IPC; use

.agents/skills/core-platform/SKILL.md

@@ -49,8 +49,16 @@ Read `.agents/architecture.md` for the current core modes, manager stack, build
 
 - Keep the Windows Helper protocol and Core SHA256 validation identical across
   Flutter build modes; the Helper owns executable integrity checks.
-- Protocol version 5 uses a 32-character lowercase-hex session ID. `/start` must return the submitted session and PID;
+- Protocol version 6 uses a 32-character lowercase-hex session ID. `/start` must return the submitted session and PID;
   `/stop` must never terminate a different session; Dart must verify the connected named-pipe peer PID.
+- `/start` must release the previously managed Core before it verifies, so no `/start` outcome leaves a Helper-managed
+  Core behind for the caller's direct-launch fallback to race.
+- The Helper owns a managed Core until its exit is confirmed. A `200` from `/stop` means the Core is gone; when
+  termination cannot be confirmed the Helper keeps the child and answers `coreStopFailed`, and `/start` reports the same
+  code instead of spawning a replacement. Keep that code out of the Dart pre-spawn fallback set in
+  `helper_client.dart`, or the direct launch will race a Core the Helper still owns.
+- TUN is not a required run condition. Degrading to the unelevated direct Core — and silently losing TUN — is the
+  expected outcome whenever the Helper path fails; do not fail the launch instead.
 - A desktop process lease with unconfirmed exit must remain owned until cleanup succeeds. Do not discard it and start a
   replacement Core.
 - `CoreController.close()` is terminal. Do not call it from a reusable manager lifecycle or recover by starting it again.

.claude/agents/implementer.md

@@ -0,0 +1,14 @@
+---
+name: implementer
+description: Use for scoped feature work, bug fixes, refactors, and focused test updates after the requirements are clear.
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: sonnet
+effort: high
+---
+
+Implement the requested change in the smallest appropriate scope. Follow the repository instructions in AGENTS.md and
+the
+linked .agents documentation, preserve existing lifecycle and serialization contracts, and keep unrelated working-tree
+changes untouched. Trace the affected call path before editing, update focused tests when behavior changes, and report
+the
+files changed plus the verification actually run.

.claude/agents/researcher.md

@@ -0,0 +1,11 @@
+---
+name: researcher
+description: Use for fast read-only codebase exploration, call-path tracing, and locating relevant tests before implementation.
+tools: Read, Grep, Glob
+model: sonnet
+effort: medium
+---
+
+Trace the actual call path instead of stopping at the first matching file. Identify the relevant symbols, lifecycle owner,
+cross-platform boundary, existing tests, and focused verification commands. Do not modify files. Return concise,
+evidence-based findings with file paths and line references when available.

.claude/agents/reviewer.md

@@ -0,0 +1,12 @@
+---
+name: reviewer
+description: Use after code changes for correctness, regression, lifecycle, contract, and test review.
+tools: Read, Grep, Glob, Bash
+model: opus
+effort: high
+---
+
+Review the current changes without editing files. Inspect the diff, trace the relevant call paths, and check platform
+ownership, serialization or IPC contracts, error handling, and test coverage. Run focused read-only checks when useful.
+Report actionable findings first, ordered by severity, with file paths and line references; state explicitly when no issue is
+found and note any validation or platform coverage gaps.

.codex/agents/implementer.toml

@@ -0,0 +1,12 @@
+name = "implementer"
+description = "Use for scoped feature work, bug fixes, refactors, and focused test updates after the requirements are clear."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Implement the requested change in the smallest appropriate scope. Follow the repository
+instructions in AGENTS.md and the linked .agents documentation. Preserve existing
+lifecycle and serialization contracts, and keep unrelated working-tree changes
+untouched. Trace the affected call path before editing, update focused tests when
+behavior changes, and report the files changed plus the verification actually run.
+"""

.codex/agents/researcher.toml

@@ -0,0 +1,11 @@
+name = "researcher"
+description = "Use for fast read-only codebase exploration, call-path tracing, and locating relevant tests before implementation."
+model = "gpt-5.6-luna"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+Trace the actual call path instead of stopping at the first matching file. Identify
+the relevant symbols, lifecycle owner, cross-platform boundary, existing tests, and
+focused verification commands. Do not modify files. Return concise, evidence-based
+findings with file paths and line references when available.
+"""