Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/architecture/rfcs/monorepo-distribution-split-v0.md
Original file line number Diff line number Diff line change
Expand Up @@ -4561,3 +4561,39 @@ view shows its independently checked result in the same conversation.
contents or activation. Full Settings journeys, actual-model adoption, total
cost, natural process drain, complete D2/D5 closure, R1/M3, full C1 acceptance
and its default cutover remain unqualified.

### 2026-11-15 — Skip automatic usage observers for existing opt-outs

- **Gap:** Python observation hints recognized fewer environment opt-outs than
the existing TypeScript usage owner. `LOOPX_USAGE_PING=off`, `CI=1` or
`DO_NOT_TRACK=yes` could still schedule observers, including binding/native
metadata discovery, before TypeScript rejected sending.
- **Delta:** one negative-only host hint preserves the owner's per-variable
trim/case semantics and skips automatic CLI, Host, quota, direct-cycle and
detached observation earlier. `LOOPX_USAGE_PING=yes` and `CI=false` remain
permitted by that hint; `DO_NOT_TRACK=false` remains blocked. TypeScript
retains positive decisions, notice, consent, generation, state and sending;
allowed payloads and business errors retain their original contracts.
- **Evidence:** against source baseline
`main@2e52541f909089181e7415e0d796f6d413c83dbf`, the real CLI counterexample
starts six detached Node children, two for each of the three opt-outs; all
return blocked. The same candidate replay starts zero, preserving CLI results
and fixture state. Source validation passes 107 Python and 55 TypeScript
tests. Eight permitted environment cases retain 48 complete observation
requests and Host error behavior under fixed fixture/clocks; this payload
comparison captures dispatch locally, alongside the real transport tests.
- **Installed scope:** fresh, non-editable only-Core installations of the
candidate and its actual composition with C1 #8266 at
`1a3740cf9e6ebad337f17967452693a9050edc81` each pass the same three real
selected `version`-CLI opt-out cases with zero observer children and unchanged
business JSON and fixture state. Each also passes 22 metadata cases and three
original Core correctness cases using real File/SQLite authority, retaining
31 raw CLI command records. The cold metadata scope is one fresh process containing 20
unselected IDs per composition; it is not 20 cold processes. Product payloads
are independently bound through source, wheel, RECORD and installed files.
- **Boundary:** this qualifies the tested source and installed-Core automatic
observer isolation, including the current-C1 composition. It does not
establish whole process/network closure, natural process drain, measured
overhead or complete-cost benefit, actual-model adoption, full D2/D5,
R1/M3, Goal completion or C1 default cutover. Preserve earlier checkpoints,
failures, budgets and acceptance requirements.
28 changes: 28 additions & 0 deletions docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -3530,3 +3530,31 @@ workspace 批准和脚本模型工作。桌面视图在采用检查后显示原
- **边界:**本次收窄 metadata discovery,不改变安装的 capability 内容或 activation。
全 Settings 旅程、真实模型采纳、总成本、自然进程 drain、完整 D2/D5 闭包、
R1/M3、完整 C1 验收及其默认切换仍未资格化。

### 2026-11-15 — 既有 opt-out 提前跳过自动 usage 观察

- **缺口:**Python observation hints 识别的环境 opt-out 少于原 TypeScript usage
owner。`LOOPX_USAGE_PING=off`、`CI=1` 或 `DO_NOT_TRACK=yes` 仍可能调度观察,
包括 binding/native metadata 发现,之后 TypeScript 才拒绝发送。
- **增量:**一个 negative-only host hint 保留原 owner 各变量的 trim/case 语义,
提前跳过自动 CLI、Host、quota、direct-cycle 和 detached observation。
`LOOPX_USAGE_PING=yes`、`CI=false` 仍通过该 hint,`DO_NOT_TRACK=false` 仍阻断。
正向 decision、notice、consent、generation、state 和发送继续由 TypeScript
持有;允许路径的 payload 和业务错误保留原契约。
- **证据:**源码基线 `main@2e52541f909089181e7415e0d796f6d413c83dbf` 的真实 CLI
反例启动六个 detached Node 子进程,每个上述 opt-out 各两个,均返回 blocked;
相同候选回放启动零个,CLI 结果和 fixture state 保持不变。源码验证通过
107 个 Python、55 个 TypeScript 测试。固定 fixture/clocks 的八个允许环境
场景保留 48 个完整 observation request 与 Host 错误行为;该 payload 对照
在本地捕获 dispatch,并与真实 transport 测试并列,范围不同。
- **安装范围:**候选及其与 C1 #8266 当前
`1a3740cf9e6ebad337f17967452693a9050edc81` 的实际组合,各自全新 non-editable
only-Core 安装通过相同三个真实 selected `version` CLI opt-out 场景,observer
子进程为零,业务 JSON 与 fixture state 保持不变。每个组合还通过 22 个 metadata
场景及三个使用真实 File/SQLite authority 的原 Core 正确性场景,并保留 31 份
raw CLI command 记录。冷 metadata 范围是每个组合一个 fresh process 内含 20 个未选 ID,不能算作
20 次冷进程。product payload 经 source、wheel、RECORD 与安装文件独立绑定。
- **边界:**本次资格化已测试的源码与 installed-Core 自动 observer 隔离,包括
current-C1 实际组合;不证明完整 process/network 闭包、自然进程
drain、实测 overhead 或完整成本收益、真实模型采用、完整 D2/D5、R1/M3、
Goal 完成或 C1 默认切换。保留既有 checkpoints、失败、预算和验收要求。
14 changes: 8 additions & 6 deletions loopx/usage_goal.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,9 @@

@contextmanager
def observe_goal_execution(runtime_root: Path, goal_id: str, *, host: str = "unknown") -> Iterator[None]:
if usage_ping._environment_suppressed():
yield
return
stop = threading.Event()
publish = None
try:
Expand All @@ -28,10 +31,7 @@ def observe_goal_execution(runtime_root: Path, goal_id: str, *, host: str = "unk
path = usage_ping.state_path()
state = json.loads(path.read_text(encoding="utf-8"))
generation = state.get("generation")
if (goal_id and generation and state.get("consent") != "disabled"
and os.environ.get("LOOPX_USAGE_PING") != "0"
and os.environ.get("DO_NOT_TRACK") != "1"
and os.environ.get("CI") != "true"):
if goal_id and generation and state.get("consent") != "disabled":
key = hashlib.sha256(json.dumps([generation, str(runtime_root.resolve()), goal_id]).encode()).hexdigest()
wall = time.time_ns() // 1_000_000
origin = time.monotonic()
Expand Down Expand Up @@ -101,12 +101,12 @@ def observe_quota_cycle(*, registry_path: Path, runtime_root: Path, goal_id: str
at: int, host: str) -> None:
"""Detach binding discovery and session metadata lookup from quota latency."""
try:
if usage_ping._environment_suppressed():
return
import sys
state = json.loads(usage_ping.state_path().read_text(encoding="utf-8"))
if state.get("consent") == "disabled" or not state.get("generation"):
return
if os.environ.get("LOOPX_USAGE_PING") == "0" or os.environ.get("DO_NOT_TRACK") == "1" or os.environ.get("CI") == "true":
return
usage_ping._detach({"registry": str(registry_path), "runtime": str(runtime_root),
"goal": goal_id, "agent": agent_id, "turn": turn_id,
"phase": phase, "at": at, "host": host,
Expand Down Expand Up @@ -155,6 +155,8 @@ def _bound_codex_session(registry_path: Path, goal_id: str, agent_id: str | None


def _dispatch_cycle(request) -> None:
if usage_ping._environment_suppressed():
return
path = Path(request["path"])
state = json.loads(path.read_text(encoding="utf-8"))
if state.get("consent") == "disabled" or state.get("generation") != request["generation"]:
Expand Down
18 changes: 17 additions & 1 deletion loopx/usage_ping.py
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
import sys
import tempfile
import time
from collections.abc import Mapping
from contextvars import ContextVar
from datetime import datetime, timezone
from pathlib import Path
Expand Down Expand Up @@ -139,12 +140,25 @@ def control(action: str, path: Path | None = None, **fields: Any) -> dict[str, A
return payload


def _environment_suppressed(environment: Mapping[str, str] | None = None) -> bool:
"""Negative-only host hint; the TS owner still decides every observation."""
env = os.environ if environment is None else environment
# Match ECMAScript String.trim, including FEFF and excluding U+0085.
whitespace = (" \t\n\r\v\f\u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005"
"\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff")
return (
env.get("LOOPX_USAGE_PING", "").strip(whitespace).lower() in {"0", "false", "no", "off"}
or env.get("DO_NOT_TRACK", "").strip(whitespace) not in {"", "0"}
or env.get("CI", "").strip(whitespace).lower() not in {"", "0", "false"}
)


def begin(command: str) -> tuple[str, float] | None:
"""Read a small host hint; do not start a synchronous Node process on warm commands."""
_observation.set({})
# Negative-only scheduling hints for common unattended environments. These
# cannot authorize collection; TS still checks every supported switch value.
if os.environ.get("LOOPX_USAGE_PING") == "0" or os.environ.get("DO_NOT_TRACK") == "1" or os.environ.get("CI") == "true":
if _environment_suppressed():
return None
# Whole-runtime migration includes this machine state. Detached observation
# would invalidate its preview or rollback receipt even with other hosts stopped.
Expand Down Expand Up @@ -239,6 +253,8 @@ def _pin_caller_paths(request: dict[str, Any]) -> dict[str, Any]:


def _detach(request: dict[str, Any], *, command: list[str] | None = None) -> None:
if _environment_suppressed():
return
request = _pin_caller_paths(request)
kwargs: dict[str, Any] = {"stdin": subprocess.PIPE, "stdout": subprocess.DEVNULL,
"stderr": subprocess.DEVNULL, "close_fds": True,
Expand Down
42 changes: 42 additions & 0 deletions tests/test_usage_goal.py
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,48 @@ def test_disabled_observer_starts_no_worker_or_process(tmp_path, monkeypatch):
pass


@pytest.mark.parametrize("switch,value", [
("LOOPX_USAGE_PING", "off"), ("DO_NOT_TRACK", "yes"),
("DO_NOT_TRACK", "false"), ("CI", "1"), ("CI", " YES "),
])
@pytest.mark.parametrize("entrypoint", ["host", "quota", "direct_cycle"])
def test_environment_opt_out_skips_host_and_binding_work(tmp_path, monkeypatch, switch, value, entrypoint):
monkeypatch.setattr(usage_ping, "select_default_runtime_root", lambda: tmp_path)
for name in ("CI", "DO_NOT_TRACK", "LOOPX_USAGE_PING"):
monkeypatch.delenv(name, raising=False)
monkeypatch.setenv(switch, value)
usage_ping.state_path().write_text(json.dumps({"generation": "fixture", "consent": "enabled"}))
workers, sends, bindings = [], [], []
monkeypatch.setattr(threading.Thread, "start", lambda worker: workers.append(worker.name))
monkeypatch.setattr(usage_ping, "_detach", sends.append)
if entrypoint == "host":
error = ValueError("original Host failure")
with pytest.raises(ValueError) as caught:
with usage_goal.observe_goal_execution(tmp_path, "fixture-goal"):
raise error
assert caught.value is error
else:
registry, rollout = _bound_fixture(tmp_path, monkeypatch)
original = usage_goal._bound_codex_session

def read_binding(*args):
result = original(*args)
bindings.append(result)
return result

monkeypatch.setattr(usage_goal, "_bound_codex_session", read_binding)
if entrypoint == "quota":
usage_goal.observe_quota_cycle(registry_path=registry, runtime_root=tmp_path, goal_id="goal",
agent_id="agent", turn_id="turn", phase="start", at=0, host="codex-app")
else:
usage_goal._dispatch_cycle({"path": str(usage_ping.state_path()), "generation": "fixture",
"registry": str(registry), "runtime": str(tmp_path), "goal": "goal", "agent": "agent",
"turn": "turn", "phase": "start", "at": 0, "host": "codex-app"})
assert workers == []
assert sends == []
assert bindings == []


def test_periodic_observation_does_not_need_turn_completion(tmp_path, monkeypatch):
monkeypatch.setattr(usage_ping, "select_default_runtime_root", lambda: tmp_path)
usage_ping.state_path().write_text(json.dumps({"generation": "fixture", "consent": "enabled"}))
Expand Down
85 changes: 85 additions & 0 deletions tests/test_usage_ping.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
import os
import runpy
import select
import shutil
import socket
import subprocess
import sys
Expand Down Expand Up @@ -310,6 +311,90 @@ def test_first_disclosure_respects_policy_overrides(isolated, monkeypatch, capsy
assert capsys.readouterr().err == ''


@pytest.mark.parametrize('switch,value', [
('LOOPX_USAGE_PING', 'off'), ('LOOPX_USAGE_PING', ' FALSE '),
('LOOPX_USAGE_PING', '\ufeffOFF\ufeff'), ('DO_NOT_TRACK', 'yes'),
('DO_NOT_TRACK', 'false'), ('CI', '1'), ('CI', ' YES '),
])
@pytest.mark.parametrize('current_notice', [False, True])
def test_environment_opt_out_skips_automatic_cli_transport(
isolated, monkeypatch, capsys, switch, value, current_notice,
):
# Real business dispatch and enabled hints prevent missing state or consent
# from masking automatic disclosure or warm-command transport attempts.
usage_ping.state_path().write_text(json.dumps({
'generation': 'fixture', 'consent': 'enabled',
'notice': {'version': 6 if current_notice else 0},
}))
monkeypatch.setenv(switch, value)
attempts = []

def unavailable_command():
attempts.append('transport')
raise OSError('fixture transport unavailable')

monkeypatch.setattr(usage_ping, '_command', unavailable_command)
assert main(['version', '--format', 'json']) == 0
captured = capsys.readouterr()
assert json.loads(captured.out)['ok'] is True
assert captured.err == ''
assert attempts == []


@pytest.mark.parametrize('switch,value', [
('LOOPX_USAGE_PING', 'off'), ('DO_NOT_TRACK', 'yes'), ('CI', '1'),
])
@pytest.mark.parametrize('producer', ['finish', 'verified_return', 'direct', 'python_child'])
def test_environment_opt_out_fences_late_or_direct_observation(
isolated, monkeypatch, switch, value, producer,
):
usage_ping.state_path().write_text(json.dumps({
'generation': 'fixture', 'consent': 'enabled', 'notice': {'version': 6},
}))
monkeypatch.setenv(switch, value)
monkeypatch.setattr(subprocess, 'Popen', lambda *a, **k: pytest.fail('opt-out spawned a child'))
monkeypatch.setattr(usage_ping, '_pin_caller_paths', lambda *a: pytest.fail('opt-out resolved caller paths'))
if producer == 'finish':
usage_ping.finish(('fixture', time.monotonic()), 'version', 0)
elif producer == 'verified_return':
usage_ping.observe_verified_return()
else:
usage_ping._detach({'path': 'caller-relative-state'}, command=(
[sys.executable, '-P', '-m', 'loopx.usage_goal'] if producer == 'python_child' else None
))


def test_environment_hint_matches_the_typescript_owner():
node = shutil.which('node')
if node is None:
pytest.skip('TypeScript owner parity requires the supported Node runtime')
# DNT differs from CI/PING. JS trims FEFF but not U+0085; Python's default
# strip has the opposite behavior for these two characters.
values = ['', '0', '1', 'false', 'true', 'no', 'off', 'yes', 'unknown',
' FALSE ', ' OFF ', ' YES ', '\ufeff0\ufeff', '\ufeffOFF\ufeff',
'\ufefffalse\ufeff', '\u00850\u0085', '\u0085off\u0085']
environments = [{}] + [{key: value} for key in ('LOOPX_USAGE_PING', 'DO_NOT_TRACK', 'CI') for value in values]
environments += [
{'LOOPX_USAGE_PING': 'yes', 'DO_NOT_TRACK': '0', 'CI': 'false'},
{'LOOPX_USAGE_PING': 'off', 'DO_NOT_TRACK': 'yes', 'CI': '1'},
]
owner = (Path(usage_ping.__file__).parent / 'control_plane/runtime/usage_statistics.ts').as_uri()
script = f'''import {{ blockedBy }} from {json.dumps(owner)};
let input=''; for await (const chunk of process.stdin) input+=chunk;
const reasons=JSON.parse(input).map(env=>blockedBy({{consent:'disabled'}},
{{env,version:'1.0.0',python:'3.13',channel:'source'}},'unused'));
process.stdout.write(JSON.stringify(reasons));'''
result = subprocess.run([node, '--no-warnings', '--experimental-strip-types', '--input-type=module', '-e', script],
input=json.dumps(environments), capture_output=True, text=True, timeout=20, check=True)
reasons = json.loads(result.stdout)
assert len(reasons) == len(environments)
for env, reason in zip(environments, reasons):
# Disabled consent makes the existing owner return before filesystem or
# sending when no environment suppressor exists; this does not enable it.
expected = reason in {'LOOPX_USAGE_PING', 'DO_NOT_TRACK', 'CI'}
assert usage_ping._environment_suppressed(env) is expected, (env, reason)


def test_real_agent_cli_keeps_json_clean_and_sends_only_after_disclosure(isolated, collector, monkeypatch):
endpoint, received, accepted, release = collector
monkeypatch.setenv('LOOPX_USAGE_PING_ENDPOINT', endpoint)
Expand Down
Loading