Merge reviewed M1 main sync into generated Turn contracts

Signed-off-by: song <liusongstep@gmail.com>

Author: songoow

CONTRIBUTING.md

@@ -79,26 +79,20 @@ Before adding or consolidating a public smoke, use the bilingual
 [good smoke guide](docs/development/good-smokes.md) to define its durable
 invariant, independent oracle, cadence, and public-safe fixture boundary.
 
-Install and verify the checkout:
+For source development, run commands from the repository or dedicated worktree
+root with `uv`. It manages a compatible Python and installs the current checkout
+in the project environment, keeping checks separate from a globally installed
+LoopX release. See the [local validation commands](docs/development/testing-and-quality.md#local-validation-environment--本地验证环境)
+for environment, lockfile, and CI boundaries.
 
 ```bash
-git clone https://github.com/huangruiteng/loopx ~/loopx
-~/loopx/scripts/install-local.sh
-export PATH="$HOME/.local/bin:$PATH"
-loopx doctor
-loopx demo
-```
-
-Common focused checks:
-
-```bash
-python -m pip install -e ".[test]"
-python -m ruff check tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation
-python -m mypy
-python examples/control_plane/cli-output-budget-regression-smoke.py
-python -m pytest -q
-loopx canary premerge --from-git-diff
-loopx check --scan-path loopx/ --scan-path tests/ --scan-path examples/ --scan-path docs/
+uv sync --extra test
+uv run --extra test python -m ruff check tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation
+uv run --extra test python -m mypy
+uv run --extra test python examples/control_plane/cli-output-budget-regression-smoke.py
+uv run --extra test python -m pytest -q
+uv run --extra test loopx canary premerge --from-git-diff
+uv run --extra test loopx check --scan-path loopx/ --scan-path tests/ --scan-path examples/ --scan-path docs/
 git diff --check
 ```
 

docs/architecture/rfcs/harness-selection-dsh-pi-v0.md

@@ -362,6 +362,14 @@ could otherwise be read as offering it:
 * **no tool authority** — the segment is refused by the dsh sandbox itself when
   it reaches for a write, and the channel reports `trust_scope: read_only`.
 
+Because the segment cannot read anything for itself, every source it is expected
+to speak about has to be supplied by LoopX in the same bounded prompt: the
+declared evidence window and the registered-source read are composed by the Turn
+owner, cached and budgeted so a wider reach cannot slow every turn. This is a
+transport consequence, not a new authority: the segment still cannot widen its
+own scope, and any source it did not receive is a named coverage gap rather than
+evidence of no progress.
+
 The earlier typed reason `managed_host_chat_transport_unsupported` is retired
 with this change; it described a transport gap that no longer exists, and keeping
 it would have made a working host unreachable. The reasons the channel can still

docs/architecture/rfcs/harness-selection-dsh-pi-v0.zh-CN.md

@@ -292,6 +292,11 @@ dsh 片段**，把通道可见的有界历史与当前消息交给它，并返
 * **无工具权威**：片段伸手写文件时会被 dsh 沙箱本身拒绝，通道据实回报
   `trust_scope: read_only`。
 
+正因为片段自己读不到任何东西，它**被期望谈论的每一个来源都必须由 LoopX 放进同一份有界
+提示**：声明的证据窗口与已注册来源的读取由 Turn 侧组装，并带缓存与预算，因此「看得更远」
+不会拖慢每一轮。这是传输形态的后果，而不是新增权威：片段仍不能扩大自己的范围，它没有收到
+的来源是一条具名的覆盖缺口，而不是「没有进展」的证据。
+
 早先的 typed reason `managed_host_chat_transport_unsupported` 随本次变更退役：它描述的
 是当时并不存在的传输缺口，保留它会让一个可用的宿主无法被选择。通道仍可回报的原因就是
 托管宿主自己的可启动性事实（`dsh_runtime_unavailable`、

docs/architecture/rfcs/semantic-vocabulary-convergence-v0.md

@@ -331,22 +331,69 @@ negative 或 mutation-style 断言，并让各 provider 复用同一 envelope 
 经 review 的兼容理由，不得削弱或删除已有维度。禁止复制生产文本、标识、路径、日志、
 凭据或私有快照。PR 验证证据需报告 fixture schema、语义维度、provider arms 与有意差异。
 
-Install the test dependencies once:
+### Local Validation Environment / 本地验证环境
+
+Run from the repository or dedicated worktree root with `uv`. The project's
+`requires-python` declares Python `>=3.11`; it does not require an executable
+named `python3.11`. `uv` selects a compatible interpreter, creates `.venv`, and
+installs the checkout with the selected extras. Interpreter downloads depend on
+uv's download settings and network access. A system `python3` may be too old,
+and a global `loopx` may resolve to a different installed source tree.
+
+在仓库或独立 worktree 根目录使用 `uv`。`pyproject.toml` 要求 Python `>=3.11`，
+无需依赖名为 `python3.11` 的命令。uv 选择兼容解释器，在 `.venv` 中安装当前源码
+与测试依赖；能否自动下载 Python 取决于下载配置与网络。系统 `python3` 可能过旧，
+全局 `loopx` 也可能指向另一个已安装版本。
 
 ```bash
-python -m pip install -e ".[test]"
+uv sync --extra test
+uv run --extra test python -m ruff check tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation
+uv run --extra test python -m mypy
+uv run --extra test python examples/control_plane/cli-output-budget-regression-smoke.py
+uv run --extra test python -m pytest -q
+uv run --extra test loopx canary premerge --from-git-diff
+# For a fork whose PR base is upstream/main, use this instead:
+uv run --extra test loopx canary premerge --from-git-diff --git-diff-base upstream/main
+# Run one semantic smoke or check its generated inventory:
+uv run --extra test loopx canary smoke-suite --script semantic-vocabulary-drift-smoke.py
+uv run python scripts/generate_semantic_inventory.py --check
+git diff --check
 ```
 
-Run the fast repository gate:
+Confirm the interpreter and imported checkout when diagnosing a mismatch:
 
 ```bash
-python -m ruff check tests loopx/canary loopx/control_plane loopx/domain_packs loopx/presentation
-python -m mypy
-python examples/control_plane/cli-output-budget-regression-smoke.py
-python -m pytest -q
-git diff --check
+uv run python -c "import sys, loopx; print(sys.executable); print(loopx.__file__)"
 ```
 
+Canary executes Python checks with the interpreter that launched LoopX
+(`sys.executable`). Its displayed `python3` command is not a second interpreter
+selection. Keep subprocesses on `sys.executable`; use `uv run` at the developer
+entrypoint. Avoid `uvx loopx` or `uv run --no-project` when validating this
+checkout, and change into the intended worktree before running Git-based checks.
+An activated compatible environment remains a supported alternative: install
+with `python -m pip install -e ".[test]"`, then use that environment's Python
+and LoopX commands directly.
+
+Canary 使用启动 LoopX 的 `sys.executable` 执行 Python 检查，显示的 `python3`
+不是重新选择解释器。子进程继续复用 `sys.executable`，只在开发入口使用 `uv run`。
+检查当前源码时不要改用 `uvx loopx` 或 `uv run --no-project`；Git diff 检查前先进入
+目标 worktree。已有兼容虚拟环境也可用 `python -m pip install -e ".[test]"` 安装源码，
+随后直接使用该环境的命令。
+
+The repository does not currently track `.python-version` or `uv.lock`. `uv`
+creates a local lockfile during resolution; keep that generated file out of
+unrelated PRs. Introducing a shared lock or interpreter pin is a separate
+repository policy change. Do not claim identical environments from
+`requires-python` alone, or use `--locked` before a reviewed lockfile exists.
+CI keeps its explicit Python versions and pinned/hash-checked installation
+paths. Historical validation receipts keep the commands that actually ran.
+
+当前仓库未跟踪 `.python-version` 或 `uv.lock`。uv 解析依赖时生成的本地锁文件不要
+混入无关 PR；共享锁文件与解释器版本固定应单独评审。最低版本要求不等于环境完全
+可复现，没有已评审锁文件时也不使用 `--locked`。CI 保留显式 Python 版本与固定依赖／
+哈希校验的安装路径，历史验证记录保留实际执行过的命令。
+
 `.github/workflows/python-tests.yml` runs this fast lane for relevant Python
 pull requests. It intentionally excludes provider-backed evaluation and the
 full smoke catalog, so ordinary iteration does not depend on credentials,
@@ -377,7 +424,7 @@ Sonar 只复用同一次 run 的 XML，不重复测试、不跨 run 取产物。
 Sonar，测试 job 不接收 Sonar secret。触发范围取原有两套 workflow 的并集；纯前端
 PR 使用前述豁免，Sonar 配置变更仍全量运行，包括没有 token 的 fork。
 
-Reproduce one shard locally with `python -m pytest -q -n 2 --splits 4 --group 1
+Reproduce one shard locally with `uv run --extra test python -m pytest -q -n 2 --splits 4 --group 1
 --splitting-algorithm least_duration --cov=loopx`. Omit the split arguments to
 run the complete suite locally. 全量本地测试仍省略分片参数即可。
 

docs/architecture/rfcs/semantic-vocabulary-convergence-v0.zh-CN.md

@@ -238,12 +238,49 @@ the window are outside coverage, not evidence of no progress, and the newest
 finding for a Goal is never dropped by the window bound.
 
 The same block declares `sources`: the local registry source plus every
-configured SSH host alias with its read status and scope. Declaring a source
-performs no remote connection and grants no authority; reading remote rows still
-requires the explicit bounded remote read path and its before/after scope checks.
-A declared but unread source is a named coverage gap. The manager must state the
-window and the sources it actually read, and must not present a single-day read
-or an unread host as whole coverage.
+SSH host this machine **registered** for LoopX evidence (an `evidence_ssh_hosts`
+grant on any channel), with its read status and scope — not every configured SSH
+alias, since an operator's `git` host or personal jump host holds no Core state
+and only adds prompt noise. Declaring a source performs no remote connection and
+grants no authority. A declared but unread source is a named coverage gap. The
+manager must state the window and the sources it actually read, and must not
+present an unread host as whole coverage.
+
+The window itself is a selected decision rather than a discovered fact:
+`days_source` reports `product_default`, `explicit_config`
+(`LOOPX_MANAGER_EVIDENCE_WINDOW_DAYS`, 1..30) or `explicit_argument`, beside
+`days_default`, `days_env_var`, `days_bounds` and `days_reason`. A missing,
+out-of-bounds or unreadable explicit value keeps the shipped default and reports
+its reason, so a misconfiguration can neither widen the prompt nor answer a
+narrower window than it declares.
+
+## A prompt-only segment receives the declared source read
+
+An interactive endpoint reads a declared remote source on demand and pays no
+source latency. A prompt-only steward segment has no read tool, so a declared
+source it never receives is a coverage gap it cannot close. In that case the Turn
+owner reads the registered sources before the segment starts and adds a
+`manager_remote_evidence_v0` block, with `remote_read` declaring `inline_in_prompt`
+rather than `on_demand_tool` in `evidence_window`.
+
+The read is bounded so it cannot slow every Turn: one dial per Turn, at most two
+hosts, nine seconds per host inside a ten-second Turn budget, and eight portfolio
+rows per host. A read inside `ttl_seconds` (ten minutes) is served from cache
+instead of dialling again, and cache entries are keyed by host, window and the
+exact grant scope, so a changed grant or window re-reads rather than answering
+from a narrower cached read. The read reuses the same `read_remote` path and its
+before/after scope checks, so it never widens authority. The declaration and the
+read use the same SSH configuration, so one packet cannot call a host
+unconfigured and read it in the same Turn.
+
+Every declared source carries a typed outcome in the same block: `read` or
+`cached` with `read_at` and `age_seconds`; `unavailable` with its reason, the last
+successful read and a `coverage_effect`; `not_configured` for alias drift; or
+`deferred_budget` with the last successful read. A failed read keeps its last
+successful rows only as `source_freshness: "stale"` with
+`remote_source_rows_are_stale` in `limitations`. A stale or unavailable source is
+a named coverage gap: it must never be presented as current progress, and it must
+never be read as no progress. A source read failure never fails the Turn.
 
 ## A bounded portfolio with explicit coverage
 

docs/development/testing-and-quality.md

@@ -310,14 +310,21 @@ The shipped version-1 database keeps one full projection per retained row, so it
 cannot be read by the version-2 provider. `sqlite_authority_migration.ts`
 migrates one Goal database in place: it reads the frozen version-1 rows, proves
 every stored commit digest, writes the checkpoint/delta log, proves that each
-written delta reconstructs its projection, requires the commit count to match,
-swaps tables and updates the schema version inside a single
+written delta reconstructs its projection, reads the not-yet-swapped tables back
+and replays them through the store's own delta decoder, requires the commit
+count to match, swaps tables and updates the schema version inside a single
 `BEGIN IMMEDIATE` transaction. Any failure rolls back and leaves version 1
 untouched; a second run reports `already_current`; a rewritten proof, a
 mismatched goal/incarnation or an existing swap target fails closed. Cursors,
 operation IDs, commit digests, provider revisions, receipts, events and scan
 pages are byte-identical after the migration.
 
+Retained projections keep every JSON object key the version-1 provider accepted,
+including an empty key and a `__proto__` key: a database the previous provider
+could read must not become one the version-2 provider cannot. The replay proof
+is what keeps that promise honest, because identical identity and digest columns
+alone would not show that a migrated state log is unreadable.
+
 A version-1 database that published only its schema and metadata — the state a
 goal leaves behind when it selected the provider and never committed — migrates
 to an equally empty version-2 database instead of failing, so the operator is
@@ -390,4 +397,8 @@ delta”：活跃头读取只用自己的行、对应提交和游标连续性自
 才写入，`--expected-identity` 可拒绝并非操作者所指的 incarnation，失败保持 v1
 原样）。只发布过 schema 与 metadata、从未提交的 v1 库会迁移成同样为空的 v2 库，
 不会让操作者落在两个 provider 都不接受的状态。迁移不改 cursor、operation id、
-commit digest、provider revision、receipt、event 或 scan 页面字节。
+commit digest、provider revision、receipt、event 或 scan 页面字节。迁移在提交前
+还会把刚写入的表读回来、用 store 自己的 delta 解码器重放一遍：只核对搬过去的
+标识与摘要无法证明新的状态日志可读。v1 能接受的 JSON key（包括空字符串和
+`__proto__`）在 v2 中保持同样的数据语义，迁移不会把原本可读的库变成读不出来的
+状态。

docs/reference/protocols/manager-evidence-and-continuity-v0.md

@@ -246,9 +246,14 @@ def _run_turn(args: argparse.Namespace) -> int:
     with tempfile.TemporaryDirectory(prefix="loopx-steward-managed-chat-") as directory:
         root = Path(directory)
         store = ChatSessionStore(root / "store")
+        # A real registry keeps this on the collected path the steward actually
+        # runs, instead of the registry-unavailable envelope.
+        registry = root / "registry.global.json"
+        registry.write_text(json.dumps({"goals": []}), encoding="utf-8")
         runtime = ChatRuntimeController(
             store=store,
             codex_bin="fixture-codex",
+            registry_path=registry,
             hard_timeout_sec=args.timeout_seconds,
         )
         try:
@@ -305,10 +310,20 @@ def _run_turn(args: argparse.Namespace) -> int:
             "manager_evidence_window_v0" in evidence_text
             and '"applies_to": "recent_delivery_history"' in evidence_text
             and '"receipt_detail_policy": "latest_full_per_goal"' in evidence_text
+            and '"days_source": "product_default"' in evidence_text
+            and '"days_bounds"' in evidence_text
+            and '"remote_read": "inline_in_prompt"' in evidence_text
             and '"sources"' in evidence_text
             and '"declared_unread_sources"' in evidence_text,
             "the prompt-only segment must receive the bounded window and declared sources",
         )
+        _assert(
+            "manager_remote_evidence_v0" in evidence_text
+            and '"read_status": "not_read"' in evidence_text
+            and '"declared_source_count": 0' in evidence_text,
+            "a prompt-only segment must receive the declared source read, and this "
+            "fixture registers no host so the read stays empty instead of dialling",
+        )
         payloads = [
             json.loads(item["body"])
             for item in CAPTURED_REQUESTS

docs/reference/sqlite-authority-store.md

@@ -910,6 +910,7 @@ def fake_run_gh_json(args: list[str], *, cwd: Path | None = None) -> object:
         "behavior_change_disclosure",
         "guidance_vs_obligation",
         "durable_smoke_value",
+        "semantic_alignment",
     }, requirements
     assert requirements["symbol_map"]["item_count"] == {"minimum": 2, "maximum": 5}
     assert "caller_evidence" in requirements["symbol_map"]["item_fields"]
@@ -966,6 +967,7 @@ def fake_run_gh_json(args: list[str], *, cwd: Path | None = None) -> object:
         "change_proportionality": ["disproportionate", "not_yet_proven"],
         "default_off_isolation": ["not_isolated", "not_yet_proven"],
         "authority_semantics": ["misleading", "not_yet_proven"],
+        "semantic_alignment": ["not_yet_proven", "violated"],
     }
     assert execution["finding_contract"]["findings_first"] is True
     first_plan = first["review_plan"]