[hidb4ai]

Which issue or RFC does this PR close?

Extracts the independent local Unix-socket transport support from #2264. It can merge directly into master without the RFC #2086 inference or context changes.

Rationale for this change

Local deployments need to expose the Server over a private Unix-domain socket while preserving authentication, existing API/MCP behavior, and reliable restart. Socket startup and cleanup must respect path ownership and avoid deleting unrelated files or live listeners.

What changes are included in this PR?

• Add an explicit UDS listener configuration, validation, private path handling, and safe stale-socket recovery/cleanup. Support an operator-declared external HTTPS scheme for trusted TLS proxies without trusting forwarded peer headers.
• Wire Server settings, command-line configuration, local service launch, and operations restrictions through the same listener contract. Resolve JSON and flat listener settings using Server precedence, and preserve nonzero startup failure status on supported Uvicorn versions.
• Add bilingual deployment/configuration documentation and real local socket/authentication/MCP/restart regressions.

Are there any user-facing changes?

Local deployments can opt into a Unix socket. A trusted TLS-terminating proxy can use POWERCONTEXT_SERVER_HTTP_UDS_EXTERNAL_SCHEME=https to preserve Dashboard origin and Secure-cookie behavior; forwarded IP headers remain untrusted. Existing TCP/HTTPS configuration remains the default. Unsupported combinations fail configuration validation. No HTTP API, database table, or migration is added.

How was this change tested?

• Focused settings, CLI/configuration, service, operations, transport, and real Server UDS regressions: 375 passed, 2 skipped. One existing launcher-import test still exceeded its unchanged 10-second limit locally. Interleaved measurements using the same interpreter and working directory also exceeded that limit on the pre-change source (10.7–10.8 seconds versus 10.5–11.4 seconds after the change); all measured processes exited normally.
• make check: passed, including lint, types, lock consistency, and integration manifest checks.
• UDS end-to-end tests start real local processes and cover authentication, normal context preparation, MCP, restart, path protection, and HTTPS proxy Dashboard login. A separately installed supported uvicorn==0.35.0 returned exit code 3 for real lifespan startup failure. These checks are independent of the context reuse/check feature.

AI usage statement

OpenAI Codex assisted with implementation, scope separation, regression tests, documentation, and validation.

[hidb4ai]

Reviewed commit 2e20bcc. Three correctness issues remain in HTTPS-proxy Dashboard access, JSON listener configuration, and startup exit status on a supported Uvicorn version. Changes are needed before merge; reproductions and required behavior are attached inline.

[hireview001]

• CI failed: tests (3.11, unit) (failure).
• CI failed: tests (3.12, unit) (failure).
• CI failed: tests (3.14, unit) (failure).
• CI failed: tests (3.13, unit) (failure).
• CI failed: Main (failure). Failed steps: tests (3.13, unit) / Run unit tests; tests (3.14, unit) / Run unit tests; tests (3.12, unit) / Run unit tests.

[hireview001]

• Resolve merge conflicts with the target branch.
• CI failed: tests (3.11, unit) (failure).
• CI failed: tests (3.12, unit) (failure).
• CI failed: tests (3.14, unit) (failure).
• CI failed: tests (3.13, unit) (failure).
• CI failed: Main (failure). Failed steps: tests (3.13, unit) / Run unit tests; tests (3.14, unit) / Run unit tests; tests (3.12, unit) / Run unit tests.

[knqiufan]

Reviewed 791874a. The existing wizard-repair discussion is not duplicated. One additional supported Desktop/Ops wire-contract mismatch is inline.

[hireview001]

LGTM

[AlexStocks]

在 head a4e54717 上复核完毕，记录结论。

已确认落地

• knqiufan 的 ops/runtime.py 线程：两个 producer 现在都返回 configuration_invalid，Desktop 的 OpsErrorCode 可直接解码，test_repair_rejects_uds_with_supported_configuration_error_without_mutation 固定了 wire 值（我在该线程里有独立复现与新 head 的确认回复）。
• configuration.py:85 的 has_uds_configuration() 走 _http_configuration_values()，与 ServerSettings 一样做大小写归一，POWERCONTEXT_SERVER_HTTP='{"UDS": ...}' 不再漏判。
• config_wizard.py 改用 has_uds_configuration(original) / has_uds_configuration(original, os.environ)，不再校验可编辑的 TCP 端口字段，坏端口仍能进既有修复流程。
• server/cli.py:844 的 if not server.started 分支保留了 typer.Exit(3)。

仍然存在的一处

server/cli.py:842 的 uvicorn.Config(..., proxy_headers=False) 没有变，hidb4ai 那条「受信任 UDS 反向代理下 Dashboard 登录拿不到外部 HTTPS scheme」的 P2 在原线程里已 resolve，但代码没改。如果是有意只支持直连 UDS，建议在 docs/*/docs/integrations 或 operate 里写明这一点；否则这条还应该跟进。

本地验证（Windows，head 源码树）

• tests/test_server_uds.py → 4 passed, 37 skipped（POSIX-only 用例自动跳过）
• tests/test_ops_local_policy.py → 20 passed, 1 skipped
• tests/test_ops_installer.py -k uds → 1 skipped（POSIX-only）

完整的 tests/test_ops_installer.py 在本机会卡住（安装类用例），没有继续追；UDS 相关面已在上面覆盖。

[AsperforMias]

no obviously significant problem for me, LGTM

[hidb4ai]

Reviewed a4e5471. One reproducible shutdown-cleanup issue remains; details are inline.

[hidb4ai]

Regarding the HTTPS-proxy scheme concern: this is already handled by POWERCONTEXT_SERVER_HTTP_UDS_EXTERNAL_SCHEME=https, with the proxy preserving the public Host header. The UDS Server path wraps the application in UnixSocketExternalScheme, so the ASGI request has the configured external scheme. proxy_headers=False intentionally keeps client-supplied forwarding headers from granting trust. The setting is documented in English and Chinese.

Replayed both cases using a real Server process and a local TLS-terminating proxy forwarding over the Unix socket: with the explicit HTTPS setting, Dashboard login returns 303 and a Secure/HttpOnly/SameSite=strict cookie; without it, the HTTPS-origin request returns 403 with no cookie. Mismatched origins also return 403. Both cases passed.