tcc-venv 0.1.0__tar.gz

tcc_venv-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+# Mirrors mo22/reslock's release path: a published GitHub release (tag vX.Y.Z)
+# triggers a build + PyPI trusted publishing via OIDC (no stored token).
+# The `pypi` environment's trusted publisher only authorizes on `release` events,
+# so workflow_dispatch builds but cannot publish.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v8.0.0
+      - run: uv build
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

tcc_venv-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# venv
+.venv/
+venv/
+
+# Claude / agent local state
+.claude/settings.local.json
+.claude/.claude_state.json
+.claude/*.lock
+
+# macOS
+.DS_Store

tcc_venv-0.1.0/AGENTS.md

@@ -0,0 +1,89 @@
+# AGENTS.md — tcc-venv
+
+Project-level instructions and design notes for agents working in this repo.
+Tool-agnostic; `CLAUDE.md` is a symlink to this file.
+
+## What this is
+
+`tcc-venv` installs a stable, codesigned **macOS TCC launcher** into a uv/venv so
+Full Disk Access / Automation grants survive `uv sync` / Python upgrades and show a
+per-project name in the permission dialog.
+
+The core problem: macOS TCC keys privacy grants on the *binary identity* (path +
+code-signing identity / cdhash) of the responsible process. A uv/venv `python` lives
+at a version-pinned, churning path (`.../cpython-3.12.x-macos.../bin/python3.12`),
+so every interpreter upgrade looks like a *different* app to TCC and silently drops
+the grant. `tcc-venv` interposes a tiny signed C launcher with a **stable identity**
+that the user grants once.
+
+## Layout
+
+```
+src/tcc_venv/
+  cli.py          # the `tcc-venv` CLI: wrap / status. build + codesign + cache logic.
+  trampoline.c    # the signed launcher. self-locates its venv, spawns python, forwards signals.
+  __init__.py
+pyproject.toml    # hatchling; force-includes trampoline.c into the wheel.
+```
+
+## How it works
+
+`tcc-venv wrap <venv>` (macOS):
+
+1. Resolve the venv (`pyvenv.cfg` must exist).
+2. Derive a friendly name (`pyvenv.cfg` `prompt`, else parent dir) and a
+   collision-resistant identifier `<prefix>.<name>.<sha256(realpath)[:8]>`, where
+   `<prefix>` defaults to `local.tcc-venv` and is overridable via
+   `--identifier-prefix` / `$TCC_VENV_IDENTIFIER_PREFIX`.
+3. Compile `trampoline.c` once per arch → cached unsigned binary.
+4. Install it as `<venv>/bin/python-tcc-<name>`, ad-hoc codesign with
+   `--identifier <identifier>`, and cache the **signed bytes** keyed by identifier.
+5. Symlink `<venv>/bin/python-tcc -> python-tcc-<name>` (the uniform name used in
+   shebangs / process control).
+
+On re-wrap (after `uv sync` blows the binary away), the **signed bytes are copied
+back** from cache, so the cdhash — and therefore the TCC grant — is identical by
+construction, immune to codesign-version drift.
+
+The trampoline:
+- self-locates its venv from its own executable path (`_NSGetExecutablePath` +
+  `realpath`), **never** trusts `$VIRTUAL_ENV` to pick the interpreter — it only
+  *refuses to run* if `$VIRTUAL_ENV` disagrees with the self-located venv.
+- `posix_spawn`s `<venv>/bin/python` (falls back to `python3`) and stays the live
+  parent (must NOT exec into python, or the child becomes the responsible process
+  and loses the grant).
+- runs the child in its **own process group** and, when interactive, hands it the
+  controlling terminal (`tcsetpgrp`) so terminal-generated signals reach the child
+  once — not the wrapper-then-child twice. Forwarded signals are blocked across
+  the spawn, and the child is started with a default mask + dispositions
+  (`POSIX_SPAWN_SETSIGMASK | SETSIGDEF`) so it actually receives them.
+- forwards SIGINT/TERM/HUP/QUIT/USR1/USR2 (directed at the wrapper) to the child's
+  process group, propagates exit status (`128 + signo` on signal death).
+
+On non-macOS the installer just symlinks `python-tcc -> python` (pure passthrough;
+the C file still compiles to a plain `execv`).
+
+## Design invariants (don't regress these)
+
+- **Bytes are project-independent.** Identity comes from `codesign --identifier` +
+  the on-disk filename, not from the compiled bytes. One cached build → every venv.
+- **Determinism over re-signing.** Always prefer copy-back of cached signed bytes;
+  only `--rebuild` mints a new cdhash (and forces re-granting FDA).
+- **Self-locate, never `$VIRTUAL_ENV`-redirect.** A leaked `$VIRTUAL_ENV` must never
+  make this binary run another project's interpreter under this identity.
+- **Stay the parent.** Spawn + wait, don't exec, so TCC inheritance holds.
+
+## Status / caveats
+
+This relies on **undocumented** TCC responsible-process inheritance and ad-hoc
+cdhash determinism that *can* drift across macOS / codesign versions. It does **not**
+bypass TCC — the user still grants explicitly in System Settings; it only stabilizes
+the identity. Treat as unofficial; verify on the macOS versions you ship to.
+
+Open release work is tracked in `tasks/release-public.md`.
+
+## Conventions
+
+- Format Python with `uvx ruff format` / `uvx ruff check --fix`.
+- No runtime deps (stdlib only). Keep it that way — this is a tiny tool.
+- The trampoline must stay warning-clean under `-Wall -Wextra`.

tcc_venv-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

tcc_venv-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moritz Möller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tcc_venv-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: tcc-venv
+Version: 0.1.0
+Summary: Install a stable, codesigned macOS TCC launcher (python-tcc) into a uv/venv
+Project-URL: Homepage, https://github.com/mo22/tcc-venv
+Project-URL: Repository, https://github.com/mo22/tcc-venv
+Project-URL: Issues, https://github.com/mo22/tcc-venv/issues
+Author-email: Moritz Möller <mm@mxs.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: codesign,full-disk-access,macos,tcc,uv,venv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# tcc-venv
+
+**Give a uv/venv Python app a stable, codesigned macOS TCC identity** — so Full Disk
+Access / Automation grants survive `uv sync` and Python upgrades, and the permission
+dialog shows a recognizable per-project name instead of `python3.12`.
+
+> macOS only for the privacy benefit. On Linux/Windows it degrades to a no-op
+> passthrough so the same launcher name works everywhere.
+
+## The problem
+
+macOS TCC (the privacy system behind *Full Disk Access*, *Automation*, *Calendar*,
+etc.) grants permissions to a specific **binary identity** — its path plus its
+code-signing identity. A Python interpreter created by `uv` lives at a churning,
+version-pinned path:
+
+```
+~/.local/share/uv/python/cpython-3.12.7-macos-aarch64-none/bin/python3.12
+```
+
+Grant *that* binary Full Disk Access, then run `uv python upgrade` or let `uv sync`
+pull a new patch release, and the path changes. To TCC it's now a **different app**:
+the grant silently stops applying and your tool starts getting "Operation not
+permitted" until you re-grant it by hand. The dialog also just says "python3.12",
+giving the user no idea which project is asking.
+
+`tcc-venv` fixes both by interposing a tiny **signed C launcher** with a stable
+identity that you grant *once*:
+
+```
+<venv>/bin/python-tcc-<project>   # signed trampoline — the stable TCC identity
+<venv>/bin/python-tcc             # -> python-tcc-<project> (uniform name for shebangs/control)
+```
+
+The launcher self-locates its venv, spawns `<venv>/bin/python` with your arguments,
+forwards signals, and propagates the exit code — staying the parent process so TCC
+attributes everything to *it*. Re-running `wrap` after `uv sync` restores the
+**identical** signed bytes from a local cache, so the cdhash — and the grant — is
+unchanged.
+
+### What it is *not*
+
+It does **not** bypass or weaken TCC. You still grant access explicitly in System
+Settings; this only stops the identity from moving out from under that grant. It
+relies on *undocumented* TCC responsible-process inheritance and ad-hoc cdhash
+determinism, both of which can change across macOS releases — treat it as unofficial
+and verify on the macOS versions you ship to.
+
+## Requirements
+
+- macOS with the **Xcode Command Line Tools** (`xcode-select --install`) — the
+  trampoline is compiled with `cc` client-side at `wrap` time.
+- Python ≥ 3.11.
+- A venv with a `pyvenv.cfg` (uv, `python -m venv`, pdm-in-venv mode — all fine).
+
+## Install
+
+```bash
+uvx tcc-venv wrap            # run without installing
+# or
+pipx install tcc-venv
+# or
+uv tool install tcc-venv
+```
+
+## Usage
+
+Run `wrap` once per venv, then point your launchers / shebangs at `python-tcc`.
+
+### With uv
+
+```bash
+cd my-project
+uv sync                      # creates ./.venv
+uvx tcc-venv wrap            # defaults to ./.venv
+```
+
+Because `uv sync` recreates the interpreter, re-run `wrap` after a sync — it restores
+the same identity from cache, so you do **not** re-grant:
+
+```bash
+uv sync && uvx tcc-venv wrap
+```
+
+### With pdm
+
+pdm can manage an in-project venv. Enable it, install, then wrap:
+
+```bash
+pdm config python.use_venv true
+pdm install                  # creates ./.venv
+uvx tcc-venv wrap .venv
+```
+
+### With a bare venv
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+uvx tcc-venv wrap .venv
+```
+
+Tip: `python -m venv --prompt myapp .venv` sets the friendly name used in the
+identity and the TCC dialog (otherwise the venv's parent directory name is used).
+
+## Grant the permission (once)
+
+After `wrap`, the binary path is printed. Add **that** binary to the relevant pane:
+
+> System Settings → Privacy & Security → Full Disk Access → **+** → select
+> `<venv>/bin/python-tcc-<project>`
+
+Automation / Calendar / Reminders prompts appear on first use. From then on, run your
+app through the shim:
+
+```bash
+.venv/bin/python-tcc my_app.py
+# or in a shebang:  #!/path/to/.venv/bin/python-tcc
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `tcc-venv wrap [venv ...]` | Install/refresh the launcher (idempotent). Defaults to `./.venv`. Accepts multiple venvs. |
+| `tcc-venv wrap --rebuild`  | Force a fresh build + sign (new cdhash — you'll need to re-grant FDA). |
+| `tcc-venv wrap --identifier-prefix PREFIX` | Override the codesign identifier prefix (default `local.tcc-venv`). |
+| `tcc-venv status [venv]`   | Show the installed shim, target, cdhash, and expected identifier. |
+
+The identifier is `<prefix>.<project>.<hash8>`, where `<prefix>` defaults to
+`local.tcc-venv` (override with `--identifier-prefix` or `$TCC_VENV_IDENTIFIER_PREFIX`)
+and `<hash8>` is derived from the venv's real path so two projects with the same name
+never share a grant.
+
+## How it works (short version)
+
+1. Compile `trampoline.c` once per architecture (cached, unsigned).
+2. Copy it to `<venv>/bin/python-tcc-<project>` and ad-hoc codesign it with a stable
+   `--identifier`.
+3. Cache the **signed bytes** by identifier; on re-wrap, copy them back so the cdhash
+   is byte-identical regardless of codesign version drift.
+4. Symlink `python-tcc -> python-tcc-<project>`.
+
+At runtime the trampoline resolves its own path → venv, refuses to run if a stray
+`$VIRTUAL_ENV` disagrees, `posix_spawn`s the venv's `python`, forwards signals, and
+returns the child's exit status (`128 + signo` on signal death). On non-macOS it's a
+plain `exec` of the venv python with no signing.
+
+See [`AGENTS.md`](AGENTS.md) for the full design and invariants.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tcc_venv-0.1.0/README.md

@@ -0,0 +1,153 @@
+# tcc-venv
+
+**Give a uv/venv Python app a stable, codesigned macOS TCC identity** — so Full Disk
+Access / Automation grants survive `uv sync` and Python upgrades, and the permission
+dialog shows a recognizable per-project name instead of `python3.12`.
+
+> macOS only for the privacy benefit. On Linux/Windows it degrades to a no-op
+> passthrough so the same launcher name works everywhere.
+
+## The problem
+
+macOS TCC (the privacy system behind *Full Disk Access*, *Automation*, *Calendar*,
+etc.) grants permissions to a specific **binary identity** — its path plus its
+code-signing identity. A Python interpreter created by `uv` lives at a churning,
+version-pinned path:
+
+```
+~/.local/share/uv/python/cpython-3.12.7-macos-aarch64-none/bin/python3.12
+```
+
+Grant *that* binary Full Disk Access, then run `uv python upgrade` or let `uv sync`
+pull a new patch release, and the path changes. To TCC it's now a **different app**:
+the grant silently stops applying and your tool starts getting "Operation not
+permitted" until you re-grant it by hand. The dialog also just says "python3.12",
+giving the user no idea which project is asking.
+
+`tcc-venv` fixes both by interposing a tiny **signed C launcher** with a stable
+identity that you grant *once*:
+
+```
+<venv>/bin/python-tcc-<project>   # signed trampoline — the stable TCC identity
+<venv>/bin/python-tcc             # -> python-tcc-<project> (uniform name for shebangs/control)
+```
+
+The launcher self-locates its venv, spawns `<venv>/bin/python` with your arguments,
+forwards signals, and propagates the exit code — staying the parent process so TCC
+attributes everything to *it*. Re-running `wrap` after `uv sync` restores the
+**identical** signed bytes from a local cache, so the cdhash — and the grant — is
+unchanged.
+
+### What it is *not*
+
+It does **not** bypass or weaken TCC. You still grant access explicitly in System
+Settings; this only stops the identity from moving out from under that grant. It
+relies on *undocumented* TCC responsible-process inheritance and ad-hoc cdhash
+determinism, both of which can change across macOS releases — treat it as unofficial
+and verify on the macOS versions you ship to.
+
+## Requirements
+
+- macOS with the **Xcode Command Line Tools** (`xcode-select --install`) — the
+  trampoline is compiled with `cc` client-side at `wrap` time.
+- Python ≥ 3.11.
+- A venv with a `pyvenv.cfg` (uv, `python -m venv`, pdm-in-venv mode — all fine).
+
+## Install
+
+```bash
+uvx tcc-venv wrap            # run without installing
+# or
+pipx install tcc-venv
+# or
+uv tool install tcc-venv
+```
+
+## Usage
+
+Run `wrap` once per venv, then point your launchers / shebangs at `python-tcc`.
+
+### With uv
+
+```bash
+cd my-project
+uv sync                      # creates ./.venv
+uvx tcc-venv wrap            # defaults to ./.venv
+```
+
+Because `uv sync` recreates the interpreter, re-run `wrap` after a sync — it restores
+the same identity from cache, so you do **not** re-grant:
+
+```bash
+uv sync && uvx tcc-venv wrap
+```
+
+### With pdm
+
+pdm can manage an in-project venv. Enable it, install, then wrap:
+
+```bash
+pdm config python.use_venv true
+pdm install                  # creates ./.venv
+uvx tcc-venv wrap .venv
+```
+
+### With a bare venv
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e .
+uvx tcc-venv wrap .venv
+```
+
+Tip: `python -m venv --prompt myapp .venv` sets the friendly name used in the
+identity and the TCC dialog (otherwise the venv's parent directory name is used).
+
+## Grant the permission (once)
+
+After `wrap`, the binary path is printed. Add **that** binary to the relevant pane:
+
+> System Settings → Privacy & Security → Full Disk Access → **+** → select
+> `<venv>/bin/python-tcc-<project>`
+
+Automation / Calendar / Reminders prompts appear on first use. From then on, run your
+app through the shim:
+
+```bash
+.venv/bin/python-tcc my_app.py
+# or in a shebang:  #!/path/to/.venv/bin/python-tcc
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `tcc-venv wrap [venv ...]` | Install/refresh the launcher (idempotent). Defaults to `./.venv`. Accepts multiple venvs. |
+| `tcc-venv wrap --rebuild`  | Force a fresh build + sign (new cdhash — you'll need to re-grant FDA). |
+| `tcc-venv wrap --identifier-prefix PREFIX` | Override the codesign identifier prefix (default `local.tcc-venv`). |
+| `tcc-venv status [venv]`   | Show the installed shim, target, cdhash, and expected identifier. |
+
+The identifier is `<prefix>.<project>.<hash8>`, where `<prefix>` defaults to
+`local.tcc-venv` (override with `--identifier-prefix` or `$TCC_VENV_IDENTIFIER_PREFIX`)
+and `<hash8>` is derived from the venv's real path so two projects with the same name
+never share a grant.
+
+## How it works (short version)
+
+1. Compile `trampoline.c` once per architecture (cached, unsigned).
+2. Copy it to `<venv>/bin/python-tcc-<project>` and ad-hoc codesign it with a stable
+   `--identifier`.
+3. Cache the **signed bytes** by identifier; on re-wrap, copy them back so the cdhash
+   is byte-identical regardless of codesign version drift.
+4. Symlink `python-tcc -> python-tcc-<project>`.
+
+At runtime the trampoline resolves its own path → venv, refuses to run if a stray
+`$VIRTUAL_ENV` disagrees, `posix_spawn`s the venv's `python`, forwards signals, and
+returns the child's exit status (`128 + signo` on signal death). On non-macOS it's a
+plain `exec` of the venv python with no signing.
+
+See [`AGENTS.md`](AGENTS.md) for the full design and invariants.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tcc_venv-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "tcc-venv"
+version = "0.1.0"
+description = "Install a stable, codesigned macOS TCC launcher (python-tcc) into a uv/venv"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Moritz Möller", email = "mm@mxs.de" }]
+keywords = ["macos", "tcc", "codesign", "uv", "venv", "full-disk-access"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: MacOS X",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/mo22/tcc-venv"
+Repository = "https://github.com/mo22/tcc-venv"
+Issues = "https://github.com/mo22/tcc-venv/issues"
+
+[project.scripts]
+tcc-venv = "tcc_venv.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tcc_venv"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/tcc_venv/trampoline.c" = "tcc_venv/trampoline.c"

tcc_venv-0.1.0/src/tcc_venv/__init__.py

@@ -0,0 +1 @@
+"""tcc-venv — stable codesigned macOS TCC launchers for uv/venv Python apps."""

tcc_venv-0.1.0/src/tcc_venv/cli.py

@@ -0,0 +1,321 @@
+"""tcc-venv — install a stable, codesigned TCC launcher into a uv/venv.
+
+See AGENTS.md for the design. In short: on macOS each wrapped venv gets
+
+    <venv>/bin/python-tcc-<project>   # signed trampoline (stable per-project identity)
+    <venv>/bin/python-tcc -> python-tcc-<project>   # uniform shim used in shebangs/control
+
+so TCC attributes Full Disk Access / Automation to `python-tcc-<project>` instead of
+the moving Homebrew-uv / version-pinned-python paths. On non-macOS, `python-tcc` is a
+plain symlink to `python` (no TCC, pure passthrough).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+IS_MACOS = sys.platform == "darwin"
+CACHE_DIR = Path(os.environ.get("TCC_VENV_CACHE", Path.home() / ".cache" / "tcc-venv"))
+SOURCE = Path(__file__).with_name("trampoline.c")
+
+# Generic, non-personal default. The reverse-DNS-ish form is only a codesign
+# identifier string; override per-org with --identifier-prefix / the env var.
+DEFAULT_IDENTIFIER_PREFIX = "local.tcc-venv"
+CFLAGS = ["-Wall", "-Wextra", "-O2"]
+
+
+# --------------------------------------------------------------------------- #
+# helpers
+# --------------------------------------------------------------------------- #
+
+
+def _die(msg: str, code: int = 1) -> NoReturn:
+    print(f"tcc-venv: {msg}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _tool(name: str) -> str:
+    """Resolve a build tool, preferring the system copy in /usr/bin over $PATH
+    so a shadowed `codesign`/`cc` can't slip into a security-sensitive launcher."""
+    system = Path("/usr/bin") / name
+    if system.exists():
+        return str(system)
+    found = shutil.which(name)
+    if found:
+        return found
+    _die(f"required tool not found: {name}")
+
+
+def _cc() -> str:
+    """C compiler. Prefer $CC, then the absolute /usr/bin/cc — the system driver
+    shim that auto-injects the active SDK sysroot (the bare `xcrun --find cc`
+    toolchain clang does not, so it can't find <errno.h>). Fall back to $PATH."""
+    env_cc = os.environ.get("CC")
+    if env_cc:
+        return env_cc
+    if Path("/usr/bin/cc").exists():
+        return "/usr/bin/cc"
+    found = shutil.which("cc")
+    if not found:
+        _die("no C compiler (cc) found — install Xcode command line tools.")
+    return found
+
+
+def _venv_dir(arg: str | None) -> Path:
+    """Resolve the target venv. Defaults to ./.venv, accepts a venv or its bin/."""
+    candidate = Path(arg).expanduser() if arg else Path.cwd() / ".venv"
+    candidate = candidate.resolve()
+    if candidate.name == "bin":
+        candidate = candidate.parent
+    if not (candidate / "pyvenv.cfg").exists():
+        _die(f"{candidate} is not a venv (no pyvenv.cfg). Run `uv sync` first.")
+    return candidate
+
+
+def _project_name(venv: Path) -> str:
+    """Friendly project name: pyvenv.cfg `prompt`, else the venv's parent dir name."""
+    name = ""
+    cfg = venv / "pyvenv.cfg"
+    for line in cfg.read_text().splitlines():
+        if "=" in line:
+            key, _, value = line.partition("=")
+            if key.strip() == "prompt":
+                name = value.strip().strip("'\"")
+                break
+    if not name:
+        name = venv.parent.name
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip("-._") or "venv"
+    return slug
+
+
+def _identifier_prefix(args: argparse.Namespace) -> str:
+    return (
+        getattr(args, "identifier_prefix", None)
+        or os.environ.get("TCC_VENV_IDENTIFIER_PREFIX")
+        or DEFAULT_IDENTIFIER_PREFIX
+    )
+
+
+def _identity(venv: Path, prefix: str) -> tuple[str, str]:
+    """(filename, identifier). Identifier includes a hash of the venv realpath so
+    two projects with the same friendly name never share a TCC grant (Codex #6)."""
+    name = _project_name(venv)
+    digest = hashlib.sha256(str(venv).encode()).hexdigest()[:8]
+    return f"python-tcc-{name}", f"{prefix}.{name}.{digest}"
+
+
+def _arch() -> str:
+    return platform.machine() or "unknown"
+
+
+def _build_unsigned() -> Path:
+    """Compile the trampoline; cache the unsigned binary keyed by the source
+    content + compiler flags (Codex #3 — mtime is unreliable across reinstalls)."""
+    key = hashlib.sha256(
+        SOURCE.read_bytes() + b"\0" + " ".join(CFLAGS).encode()
+    ).hexdigest()[:16]
+    out = CACHE_DIR / "unsigned" / _arch() / f"{key}.bin"
+    if out.exists():
+        return out
+    out.parent.mkdir(parents=True, exist_ok=True)
+    tmp = out.with_suffix(".tmp")
+    subprocess.run([_cc(), *CFLAGS, str(SOURCE), "-o", str(tmp)], check=True)
+    os.replace(tmp, out)
+    return out
+
+
+def _codesign_show(path: Path) -> dict[str, str]:
+    res = subprocess.run(
+        [_tool("codesign"), "-dvvv", str(path)], capture_output=True, text=True
+    )
+    info: dict[str, str] = {}
+    for line in (res.stderr + res.stdout).splitlines():
+        if "=" in line:
+            key, _, value = line.partition("=")
+            info.setdefault(key.strip(), value.strip())
+    return info
+
+
+def _cdhash(path: Path) -> str:
+    return _codesign_show(path).get("CDHash", "?")
+
+
+def _verify(path: Path, identifier: str) -> bool:
+    """A signed binary is good only if it passes codesign --verify, carries the
+    expected identifier, and has a real cdhash (Codex #5)."""
+    res = subprocess.run(
+        [_tool("codesign"), "--verify", "--strict", str(path)],
+        capture_output=True,
+        text=True,
+    )
+    if res.returncode != 0:
+        return False
+    info = _codesign_show(path)
+    return info.get("Identifier") == identifier and info.get("CDHash", "?") not in (
+        "",
+        "?",
+    )
+
+
+def _atomic_install(
+    installed: Path, source: Path, identifier: str, *, sign: bool
+) -> bool:
+    """Stage `source` into a temp file beside `installed`, optionally codesign it,
+    verify it, then atomically swap it in (Codex #4 — never expose an unsigned or
+    half-written binary). Returns False if the result fails verification."""
+    tmp = installed.with_name(f".{installed.name}.tmp")
+    try:
+        shutil.copyfile(source, tmp)
+        tmp.chmod(0o755)
+        if sign:
+            # Capture codesign's chatter (e.g. "replacing existing signature",
+            # which arm64 always emits — the linker ad-hoc signs at link time);
+            # surface it only if signing actually fails.
+            res = subprocess.run(
+                [
+                    _tool("codesign"),
+                    "--force",
+                    "--sign",
+                    "-",
+                    "--identifier",
+                    identifier,
+                    str(tmp),
+                ],
+                capture_output=True,
+                text=True,
+            )
+            if res.returncode != 0:
+                _die(f"codesign failed for {installed}:\n{res.stderr.strip()}")
+        if not _verify(tmp, identifier):
+            return False
+        os.replace(tmp, installed)
+        return True
+    finally:
+        tmp.unlink(missing_ok=True)
+
+
+def _symlink(link: Path, target: str) -> None:
+    if link.is_symlink() or link.exists():
+        link.unlink()
+    link.symlink_to(target)
+
+
+# --------------------------------------------------------------------------- #
+# commands
+# --------------------------------------------------------------------------- #
+
+
+def cmd_wrap(args: argparse.Namespace) -> None:
+    prefix = _identifier_prefix(args)
+    for raw in args.venv or [None]:
+        venv = _venv_dir(raw)
+        bindir = venv / "bin"
+        shim = bindir / "python-tcc"
+
+        if not IS_MACOS:
+            _symlink(shim, "python")
+            print(f"{shim} -> python   (non-macOS passthrough)")
+            continue
+
+        filename, identifier = _identity(venv, prefix)
+        installed = bindir / filename
+        signed_cache = CACHE_DIR / "signed" / identifier
+
+        # Reuse the exact signed bytes if we have them (Codex #7: copy-back beats
+        # re-signing, so the cdhash — and thus the TCC grant — is identical by
+        # construction across uv sync / codesign version drift). The restore is
+        # verified, not trusted, so a corrupt/mismatched cache falls through to a
+        # fresh build (Codex #5).
+        restored = False
+        if signed_cache.exists() and not args.rebuild:
+            restored = _atomic_install(installed, signed_cache, identifier, sign=False)
+
+        if not restored:
+            unsigned = _build_unsigned()
+            if not _atomic_install(installed, unsigned, identifier, sign=True):
+                _die(f"codesign verification failed for {installed}")
+            signed_cache.parent.mkdir(parents=True, exist_ok=True)
+            cache_tmp = signed_cache.with_suffix(".tmp")
+            shutil.copyfile(installed, cache_tmp)
+            os.replace(cache_tmp, signed_cache)
+
+        _symlink(shim, filename)
+
+        print(f"wrapped {venv}")
+        print(f"  binary:     {installed}")
+        print(f"  shim:       {shim} -> {filename}")
+        print(f"  identifier: {identifier}")
+        print(f"  cdhash:     {_cdhash(installed)}")
+    if IS_MACOS:
+        print(
+            "\nGrant the binary Full Disk Access ONCE:\n"
+            "  System Settings -> Privacy & Security -> Full Disk Access -> add the\n"
+            "  python-tcc-<project> binary above. Automation/EventKit prompts appear\n"
+            "  on first use. Re-running `tcc-venv wrap` after `uv sync` restores the\n"
+            "  identical identity, so the grant persists."
+        )
+
+
+def cmd_status(args: argparse.Namespace) -> None:
+    venv = _venv_dir(args.venv)
+    shim = venv / "bin" / "python-tcc"
+    if not shim.is_symlink():
+        print(f"{venv}: not wrapped")
+        return
+    target = os.readlink(shim)
+    print(f"{venv}")
+    print(f"  shim:   {shim} -> {target}")
+    real = venv / "bin" / target
+    if IS_MACOS and real.exists():
+        _, identifier = _identity(venv, _identifier_prefix(args))
+        print(f"  binary: {real}")
+        print(f"  cdhash: {_cdhash(real)}")
+        print(f"  expect: {identifier}")
+
+
+def _add_prefix_arg(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--identifier-prefix",
+        default=None,
+        help="codesign identifier prefix (default: $TCC_VENV_IDENTIFIER_PREFIX or "
+        f"{DEFAULT_IDENTIFIER_PREFIX!r}); identifier is <prefix>.<project>.<hash8>",
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="tcc-venv",
+        description="Install a stable codesigned TCC launcher into a uv/venv.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_wrap = sub.add_parser("wrap", help="install python-tcc into a venv (idempotent)")
+    p_wrap.add_argument("venv", nargs="*", help="venv dir(s); default ./.venv")
+    p_wrap.add_argument(
+        "--rebuild",
+        action="store_true",
+        help="force a fresh build+sign (new cdhash — needs re-granting FDA)",
+    )
+    _add_prefix_arg(p_wrap)
+    p_wrap.set_defaults(func=cmd_wrap)
+
+    p_status = sub.add_parser("status", help="show the wrapper installed in a venv")
+    p_status.add_argument("venv", nargs="?", help="venv dir; default ./.venv")
+    _add_prefix_arg(p_status)
+    p_status.set_defaults(func=cmd_status)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

tcc_venv-0.1.0/src/tcc_venv/trampoline.c

@@ -0,0 +1,296 @@
+/*
+ * tcc-venv trampoline — a stable, codesigned launcher for a uv/venv Python app
+ * so macOS TCC (Full Disk Access / Automation) attributes grants to THIS binary
+ * instead of the moving Homebrew-uv / version-pinned-python paths.
+ *
+ * Installed by `tcc-venv` as <venv>/bin/python-tcc-<project> (macOS). It:
+ *   - self-locates its venv from its own executable path (NOT $VIRTUAL_ENV, which
+ *     could leak from another project and run the wrong interpreter under this
+ *     binary's identity — it is only honored if it AGREES with the self-located venv),
+ *   - posix_spawns <venv>/bin/python with argv[1:] appended (stays the live parent
+ *     so the child inherits this binary's TCC grant — must NOT exec into python),
+ *   - runs the child in its own process group and (when interactive) hands it the
+ *     controlling terminal, so terminal signals reach the child once — not the
+ *     wrapper and then the child again,
+ *   - forwards directed signals to the child's process group and propagates exit.
+ *
+ * The bytes are project-INDEPENDENT (the per-project identity comes from codesign
+ * --identifier + the on-disk filename, applied by the installer), so one cached
+ * build is copied to every venv.
+ *
+ * On non-macOS this file is unused — the installer symlinks python-tcc -> python
+ * directly — but the code still compiles to a plain exec of the venv python.
+ */
+#include <errno.h>
+#include <signal.h>
+#include <spawn.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+#ifdef __APPLE__
+#include <mach-o/dyld.h>
+#endif
+
+extern char **environ;
+
+static const int FORWARDED_SIGNALS[] = {
+    SIGINT, SIGTERM, SIGHUP, SIGQUIT, SIGUSR1, SIGUSR2,
+};
+#define N_FORWARDED ((int)(sizeof(FORWARDED_SIGNALS) / sizeof(FORWARDED_SIGNALS[0])))
+
+static volatile sig_atomic_t child_pid = -1;
+
+static void forward_signal(int signo) {
+    pid_t pid = (pid_t)child_pid;
+    if (pid > 0) {
+        /* Child leads its own process group; signal the whole group so any
+         * grandchildren are torn down too. */
+        kill(-pid, signo);
+    }
+}
+
+static void install_signal_handlers(void) {
+    struct sigaction action;
+    memset(&action, 0, sizeof(action));
+    action.sa_handler = forward_signal;
+    sigemptyset(&action.sa_mask);
+    action.sa_flags = SA_RESTART;
+    for (int i = 0; i < N_FORWARDED; i++) {
+        sigaction(FORWARDED_SIGNALS[i], &action, NULL);
+    }
+}
+
+/* malloc'd absolute path to this executable, symlinks resolved, or NULL. */
+static char *self_path(void) {
+    char *raw = NULL;
+#ifdef __APPLE__
+    uint32_t size = 0;
+    _NSGetExecutablePath(NULL, &size); /* sets size to the required length */
+    raw = malloc(size ? size : 1);
+    if (raw == NULL) {
+        return NULL;
+    }
+    if (_NSGetExecutablePath(raw, &size) != 0) {
+        free(raw);
+        return NULL;
+    }
+#else
+    size_t cap = 1024;
+    for (;;) {
+        char *buf = malloc(cap);
+        if (buf == NULL) {
+            return NULL;
+        }
+        ssize_t n = readlink("/proc/self/exe", buf, cap);
+        if (n < 0) {
+            free(buf);
+            return NULL;
+        }
+        if ((size_t)n < cap) {
+            buf[n] = '\0';
+            raw = buf;
+            break;
+        }
+        free(buf);
+        cap *= 2;
+    }
+#endif
+    char *resolved = realpath(raw, NULL);
+    if (resolved != NULL) {
+        free(raw);
+        return resolved;
+    }
+    return raw; /* fall back to the unresolved path if realpath fails */
+}
+
+/* Strip the last path component in place (dirname). */
+static int strip_component(char *path) {
+    char *slash = strrchr(path, '/');
+    if (slash == NULL || slash == path) {
+        return -1;
+    }
+    *slash = '\0';
+    return 0;
+}
+
+/* malloc'd "dir/leaf", or NULL. */
+static char *path_join(const char *dir, const char *leaf) {
+    size_t n = strlen(dir) + 1 + strlen(leaf) + 1;
+    char *out = malloc(n);
+    if (out == NULL) {
+        return NULL;
+    }
+    snprintf(out, n, "%s/%s", dir, leaf);
+    return out;
+}
+
+int main(int argc, char *argv[]) {
+    /* self = <venv>/bin/python-tcc-<project>  ->  venv = dirname(dirname(self)) */
+    char *venv = self_path();
+    if (venv == NULL) {
+        fprintf(stderr, "python-tcc: cannot resolve own executable path\n");
+        return 127;
+    }
+    if (strip_component(venv) != 0 || strip_component(venv) != 0) {
+        fprintf(stderr, "python-tcc: unexpected install location (not <venv>/bin/...)\n");
+        free(venv);
+        return 127;
+    }
+
+    /* Security: never let a stray $VIRTUAL_ENV redirect us to another venv. */
+    const char *venv_env = getenv("VIRTUAL_ENV");
+    if (venv_env != NULL && venv_env[0] != '\0') {
+        char *env_resolved = realpath(venv_env, NULL);
+        if (env_resolved != NULL) {
+            int mismatch = strcmp(env_resolved, venv) != 0;
+            if (mismatch) {
+                fprintf(
+                    stderr,
+                    "python-tcc: refusing to run — $VIRTUAL_ENV (%s) disagrees with my venv (%s)\n",
+                    env_resolved, venv);
+            }
+            free(env_resolved);
+            if (mismatch) {
+                free(venv);
+                return 125;
+            }
+        }
+    }
+
+    char *python = path_join(venv, "bin/python");
+    if (python == NULL) {
+        fprintf(stderr, "python-tcc: out of memory\n");
+        free(venv);
+        return 127;
+    }
+    if (access(python, X_OK) != 0) {
+        /* Fall back to python3 if a bare `python` is absent. */
+        char *python3 = path_join(venv, "bin/python3");
+        if (python3 != NULL && access(python3, X_OK) == 0) {
+            free(python);
+            python = python3;
+        } else {
+            fprintf(stderr, "python-tcc: no venv python at %s\n", python);
+            free(python3);
+            free(python);
+            free(venv);
+            return 127;
+        }
+    }
+    free(venv);
+
+    /* child argv: python + argv[1:]  (argc may be 0 in a pathological exec). */
+    int passthrough = argc > 1 ? argc - 1 : 0;
+    char **child_argv = calloc((size_t)passthrough + 2, sizeof(char *));
+    if (child_argv == NULL) {
+        fprintf(stderr, "python-tcc: out of memory\n");
+        free(python);
+        return 127;
+    }
+    child_argv[0] = python;
+    for (int i = 0; i < passthrough; i++) {
+        child_argv[i + 1] = argv[i + 1];
+    }
+    child_argv[passthrough + 1] = NULL;
+
+#ifndef __APPLE__
+    /* No TCC off-mac: just become python (cheaper, no supervisor needed). */
+    execv(python, child_argv);
+    fprintf(stderr, "python-tcc: execv %s failed: %s\n", python, strerror(errno));
+    free(child_argv);
+    free(python);
+    return 127;
+#else
+    /* Don't let the wrapper be stopped if it writes to the tty while the child
+     * owns the terminal foreground (set below). */
+    signal(SIGTTOU, SIG_IGN);
+
+    /* Block the forwarded signals across spawn + child_pid assignment so a
+     * signal arriving before the handlers are live can't kill only the wrapper
+     * and orphan python (the handlers are a no-op until child_pid is valid). */
+    sigset_t block, prev;
+    sigemptyset(&block);
+    for (int i = 0; i < N_FORWARDED; i++) {
+        sigaddset(&block, FORWARDED_SIGNALS[i]);
+    }
+    sigprocmask(SIG_BLOCK, &block, &prev);
+
+    /* Run the child in its own process group so terminal-generated signals are
+     * delivered to it once, not to the wrapper and then forwarded again. Reset
+     * its signal mask to the pre-block set (SETSIGMASK) and its dispositions to
+     * default (SETSIGDEF) — otherwise the child inherits our temporarily-blocked
+     * mask and never sees a forwarded SIGTERM. */
+    sigset_t child_defaults;
+    sigemptyset(&child_defaults);
+    for (int i = 0; i < N_FORWARDED; i++) {
+        sigaddset(&child_defaults, FORWARDED_SIGNALS[i]);
+    }
+    sigaddset(&child_defaults, SIGTTOU);
+
+    posix_spawnattr_t attr;
+    posix_spawnattr_init(&attr);
+    posix_spawnattr_setflags(
+        &attr, POSIX_SPAWN_SETPGROUP | POSIX_SPAWN_SETSIGMASK | POSIX_SPAWN_SETSIGDEF);
+    posix_spawnattr_setpgroup(&attr, 0); /* child becomes its own group leader */
+    posix_spawnattr_setsigmask(&attr, &prev);
+    posix_spawnattr_setsigdefault(&attr, &child_defaults);
+
+    pid_t pid;
+    int spawn_status = posix_spawn(&pid, python, NULL, &attr, child_argv, environ);
+    posix_spawnattr_destroy(&attr);
+    free(child_argv);
+    if (spawn_status != 0) {
+        sigprocmask(SIG_SETMASK, &prev, NULL);
+        fprintf(stderr, "python-tcc: failed to spawn %s: %s\n", python, strerror(spawn_status));
+        free(python);
+        return 127;
+    }
+
+    child_pid = (sig_atomic_t)pid;
+
+    /* Hand the controlling terminal's foreground to the child's group so an
+     * interactive REPL / input() keeps working and Ctrl-C reaches the child. */
+    int interactive = isatty(STDIN_FILENO);
+    if (interactive) {
+        tcsetpgrp(STDIN_FILENO, pid); /* pid == the child's pgid */
+    }
+
+    install_signal_handlers();
+    sigprocmask(SIG_SETMASK, &prev, NULL);
+
+    int status;
+    for (;;) {
+        pid_t waited = waitpid(pid, &status, 0);
+        if (waited == pid) {
+            break;
+        }
+        if (waited == -1 && errno == EINTR) {
+            continue;
+        }
+        if (waited == -1) {
+            fprintf(stderr, "python-tcc: waitpid failed: %s\n", strerror(errno));
+            free(python);
+            return 1;
+        }
+    }
+    child_pid = -1;
+    free(python);
+
+    /* Reclaim the terminal foreground for our own group before exiting. */
+    if (interactive) {
+        tcsetpgrp(STDIN_FILENO, getpgrp());
+    }
+
+    if (WIFEXITED(status)) {
+        return WEXITSTATUS(status);
+    }
+    if (WIFSIGNALED(status)) {
+        return 128 + WTERMSIG(status);
+    }
+    return 1;
+#endif
+}

tcc_venv-0.1.0/tasks/release-public.md

@@ -0,0 +1,79 @@
+# Task: make tcc-venv release-ready (GitHub + PyPI)
+
+Status: **open** — created 2026-06-05. Tool is built and working locally on alphagit-track;
+this task tracks the work to publish it publicly.
+
+## Goal
+Publish `tcc-venv` as a small open-source tool (GitHub repo + PyPI package) that gives
+uv/venv Python apps a stable, codesigned macOS TCC identity so Full Disk Access /
+Automation grants survive uv/python upgrades and show a per-project name in the
+permission dialog.
+
+## Current state (what already exists)
+- Package at `~/workspace/tcc-venv` (`tcc-venv` CLI, `tcc_venv` package).
+- `tcc-venv wrap <venv>` installs `<venv>/bin/python-tcc-<project>` (signed trampoline) +
+  `<venv>/bin/python-tcc` symlink (→ that on macOS, → `python` on non-macOS).
+- Verified locally: correct venv prefix via the shim, deterministic cdhash across
+  re-wrap, `$VIRTUAL_ENV` mismatch refused, signal forwarding + exit-code propagation,
+  wipe-then-rewrap restores identical identity (uv-sync-proof).
+- Codex review fixes already applied: self-locate only (no `$VIRTUAL_ENV` preference),
+  collision-resistant identifier `ai.mxs.tcc.<project>.<hash8-of-venv-realpath>`,
+  signed-bytes cache copy-back, absolute invocation (no relative shebang for control).
+
+## Blocking before any public release (verify, don't assume)
+1. **Verify Automation/EventKit inheritance on real macOS.** We only proved Full Disk
+   Access. Trigger a Reminders/Calendar/Mail (EventKit + AppleEvents) access through a
+   launchd-launched `python-tcc-<project>` and confirm the grant attaches to it (not to
+   the python child / osascript). Codex flagged these may key on the sending process.
+2. **Verify the TCC dialog/Settings display name** actually shows `python-tcc-<project>`
+   (not `python-tcc`, `python`, or the resolved path) for a bare ad-hoc CLI binary
+   invoked via the symlink. If it disappoints, fall back to a minimal signed `.app`
+   with `CFBundleName`/`CFBundleIdentifier`.
+3. **Document the foundations honestly.** It relies on *undocumented* TCC
+   responsible-process inheritance and ad-hoc cdhash determinism that can drift across
+   macOS/codesign versions. README needs a clear "unofficial, may break on a future
+   macOS" caveat + a tested-OS-version matrix.
+
+## Release checklist
+### a) GitHub
+- [ ] Create public repo `mo22/tcc-venv` (decide org/user). `gh repo create`.
+- [ ] Mirror from alphagit (`git@alpha.mxs.de:mmoeller/tcc-venv.git`) → add GitHub remote.
+- [ ] CI: GitHub Actions on macOS runner — build the trampoline, run the behavioral
+      tests (venv prefix, determinism, `$VIRTUAL_ENV` guard, signals, exit codes).
+- [ ] Standard audit stack per global setup (osv-scanner, gitleaks) — light, few deps.
+
+### b) Deploy to PyPI
+- [x] Confirm the `tcc-venv` name is free on PyPI (it is, 2026-06-05). Only `tcc-venv`
+      is published; `python-tcc` is the installed binary/shim name, never a package.
+      License: MIT.
+- [ ] Trusted-publishing (PyPI OIDC) via GitHub Actions on tag, or manual `uv build` +
+      `twine`/`uv publish`.
+- [ ] `pipx install tcc-venv` / `uvx tcc-venv` smoke test from the published artifact.
+- [ ] Note: wheel ships `trampoline.c`; build happens client-side at `wrap` time (needs
+      `cc`). Document the Xcode CLT requirement.
+
+### c) Parameterize the branding
+- [x] Make the identifier prefix configurable (flag / env / config) instead of the
+      hardcoded `ai.mxs.tcc.`. Done 2026-06-05: `--identifier-prefix` flag +
+      `$TCC_VENV_IDENTIFIER_PREFIX`, default `local.tcc-venv`.
+- [ ] Make the shim/binary name prefix (`python-tcc`) overridable if needed.
+- [x] Strip any other mxs-specific assumptions (identifier prefix was the only one).
+
+### d) Docs & framing
+- [ ] README: the problem (uv/python upgrade kills TCC grants), the mechanism, install,
+      `wrap`, the uv-sync re-wrap story, the OS-version caveats.
+- [ ] **Security framing:** explicit that it does NOT bypass TCC — the user still grants
+      explicitly in System Settings; it only stabilizes the identity. Avoid reading as a
+      TCC-evasion aid.
+- [ ] Comparison / prior art note (codesign-for-TCC blog posts, why a venv-level tool).
+
+### e) Nice-to-have
+- [ ] `tcc-venv unwrap` (restore plain `python-tcc` → none / clean up).
+- [ ] `tcc-venv doctor` — check FDA state where detectable, surface stale wraps after uv sync.
+- [ ] Optional `.app` bundle mode for predictable dialog naming.
+- [ ] A `uv sync` convenience wrapper or git hook that re-runs `wrap`.
+
+## Validation strategy
+Use the personal fleet as the real-world shakeout before publishing: mac-mcp,
+fileindex-mcp, webshell (agent-mcp). Keep it on alphagit until items 1–3 above are
+confirmed on the macOS versions in use.