[axisrow]

Fixes #1448, closes #1447 (package side; machine-local env cleanup documented in an issue comment).

What

git mv src tg_agent + mechanical rewrite of every reference to the old import name — zero logic changes:

• imports (from src. / import src.) and string patch/setattr/import_module targets
• logger names, argv module references (python -m src.main, Codex/ADK backend subprocesses, daemon autorestart process matching)
• entry point tg-agent = tg_agent.main:main, [tool.setuptools] package discovery/package-data keys, [tool.mutmut] source_paths, .importlinter root/contracts
• CI path args in ci.yml (ruff/jscpd/bandit targets — forced by the rename, no job/structure changes), Dockerfile CMD
• tg-agent --version now prints tg-agent <ver> (was src <ver>)
• live docs (CLAUDE.md, README, CONTRIBUTING, skills-adjacent docs); historical records (.github/release-metadata/, docs/superpowers/plans/) deliberately keep old paths
• tests/test_packaging_release.py: asserts flipped to the new layout + new regression guard

Why

The dist is named tg-agent but shipped a top-level src package: wheel collides with any other project's src, version metadata/CLI reported the wrong name (tg-agent --version → src 0.2.3), and a non-editable install couldn't serve as the self-contained fix for the stale-editable-install breakage in #1447.

Regression guard (required by the task)

tests/test_packaging_release.py::test_wheel_ships_tg_agent_package_not_src builds a wheel through the declared PEP 517 path and asserts: tg_agent/__init__.py present, no top-level src/, Name: tg-agent in dist-info, tg-agent = tg_agent.main:main in entry_points, web templates (package-data) present.

Verification

• ruff check tg_agent tests conftest.py — clean
• lint-imports --config .importlinter — 1 contract KEPT
• full suite as in CI via workspace .venv (rebased on current main):
  smoke 7 passed / 24 skipped; parallel 9907 passed, 151 skipped, 9 failed; serial 1014 passed
• the 9 parallel failures are tests/test_cli_agent_commands.py — proven pre-existing on main (identical 9 failures running the same file on detached main in the same venv; Python 3.13 GC of the tests' abandoned _fake_stream async generators → PytestUnraisableExceptionWarning under filterwarnings=error). Zero new failures from this diff.
• .venv/bin/tg-agent --version → tg-agent 0.2.4.1; python -m tg_agent.main --version — same
• fresh venv + pip install tg_agent-0.2.4.1-py3-none-any.whl with deps → tg-agent --version prints tg-agent 0.2.4.1, --help exits 0 (PATH: system tg-agent resolves to editable install from a deleted AO worktree (ModuleNotFoundError: src) #1447 end-state)
• wheel guard: tests/test_packaging_release.py::test_wheel_ships_tg_agent_package_not_src — builds a real PEP 517 wheel, asserts contents

Notes / risks

• BREAKING (import-level only): anything importing src.* must switch to tg_agent.*. CLI users of the tg-agent entry point are unaffected (same command, now resolving to a correctly named package).
• test_packaging_deps.py untouched and green.
• mutmut: the flat-src incompatibility that required the strip_src_prefix fork disappears with the rename; fork stays until the upstream PR lands (comment updated in pyproject).
• e2e/console and real-TG suites are gate-gated as before; no test policy changes.

🤖 Generated with Claude Code

[axisrow]

Requested changes. The rename itself is verified clean at head 658171f: tree-wide grep shows zero functional src references left (imports, string patch/setattr/import_module targets, argv module refs incl. the daemon-autorestart matcher and Codex/ADK subprocesses), entry point, [tool.setuptools], [tool.mutmut], .importlinter, CI path args (forced only, no structure changes), Dockerfile and the agent-facing docs are all consistent, and the wheel-content guard is a good regression net. Three findings need changes: (1) one src file survived the rename - re-created by commits merged from main after the delete and mechanically rewritten instead of removed; (2) the new wheel-build test auto-classifies as unit and lacks mutmut_skip; (3) docstring/comment references to the old name were not swept (34 dead mkdocstrings autorefs + 44 files with stale src/ path comments). Optional, summary-only: the pip-wheel build adds a one-off isolated-build cost (~10-40s) to the suite run - acceptable for the guarantee it buys.

[axisrow]

Requested changes (sweep tail only). All three findings from the previous round are verified fixed at 91eecb2: git ls-files src is empty (ghost package gone), the wheel test carries @pytest.mark.integration + @pytest.mark.mutmut_skip, and .py docstrings under tg_agent/ are clean (0 mkdocstrings autorefs with src.* left; fix hunks are comment/docstring-only, no logic drift). What remains is the same required sweep, incompletely executed outside .py files: two live published docs (docs.yml deploys them) still state wrong module/package facts and one operational script docstring points at a nonexistent module. Each is a mechanical one-liner; inline comments below (the in-package template leftover is folded into the first one because its line is an unchanged rename line and cannot carry an inline anchor). Optional, not blocking: stale src/ path comments in tests/cli_real_tg_integration (conftest.py:489/652/707 and heavy tests), docs/plans/zai-provider-support.md (historical plan), the display label print() в src/cli/ in scripts/code_health.py:193 (the scan itself is path-agnostic via the /cli/ marker and works), and the src_root parameter name in tg_agent/cli/daemon_autorestart.py:42 (cosmetic).

[axisrow]

Requested changes - one line left. Verified fixed at f3c36b8: docs/design/plugin-system.md:55 now names tg_agent.plugin_api and tg_agent/agent/tools/_registry.py, docs/testing/real-telegram.md:159 now walks tg_agent.cli.typer_commands.app, scripts/restart_daemon_if_stale.py docstring says tg_agent/ and tg_agent/cli/daemon_autorestart.py, and the optional tests/cli_real_tg_integration comment sweep from the summary was done too - thank you. The one remaining item from the previous round is the folded one: tg_agent/web/templates/agent/_threads.html:86 still says see src/agent/models.py. That file is a pure rename in this diff (no commentable lines, confirmed via the files API), so the finding is anchored on the closest patched template instead. Fix that one line (tg_agent/agent/models.py) and this PR is ready; everything else about the rename remains verified clean (zero functional src references, wheel guard green, packaging config consistent).

[axisrow]

Approving. The last remaining item is fixed at 22b7a35: tg_agent/web/templates/agent/_threads.html:86 now points to tg_agent/agent/models.py (single-line commit, nothing else touched). Final residual sweep at this head confirms the rename is complete: zero functional src references tree-wide (imports, string patch/setattr/import_module targets, argv module refs), zero mkdocstrings autorefs with old paths under tg_agent/, the only in-package match left is an unrelated JS variable named src in pipelines/create.html. All findings across the five review rounds are resolved: the ghost src/services/task_handlers/init.py removal, wheel-guard markers (integration + mutmut_skip), the docstring/comment sweep in package code, live docs (plugin-system.md, real-telegram.md), the operational script docstring, and this template pointer. Packaging config, CI path args, Dockerfile, .importlinter and agent-facing docs were verified consistent in the first round; the wheel-content guard covers the regression the task required. Branch is mergeable against main (CI run still in flight at review time - verify conclusion before merge as usual).

[axisrow]

Closing per owner decision: the full src → tg_agent rename (path A) was moved to its own sequencing slot — tracked in #1583 as a solo PR after the current waves. This PR ships that complete rename, verified (full suite green except pre-existing failures proven on main, wheel-content guard, fresh-venv install smoke), but the owner chose the minimal packaging-metadata fix first.

The rename work is preserved on this branch (ao/packaging-1448-wheel/package-rename) and can be rebased onto main when #1583 is scheduled — including the rebase-conflict resolution pattern (take main's content, re-apply the mechanical sweep) and the review findings fixed here (ghost src/ init, docstring refs, static scans).

A minimal metadata-only PR (path B: tg-agent --version prints the distribution name, metadata regression guard) follows immediately.