pythinker-code 0.31.0__tar.gz → 0.32.0__tar.gz

{pythinker_code-0.31.0 → pythinker_code-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythinker-code
-Version: 0.31.0
+Version: 0.32.0
 Summary: Pythinker Code is your next CLI agent.
 Keywords: cli,agent,ai,coding-assistant,llm,claude,openai,terminal
 Author: Mohamed Elkholy
@@ -79,7 +79,7 @@ Description-Content-Type: text/markdown
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-16a34a.svg?style=for-the-badge)](https://github.com/Pythoughts-labs/pythinker-code/blob/main/LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/Pythoughts-labs/pythinker-code/ci-pythinker-cli.yml?branch=main&label=CI&style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/Pythoughts-labs/pythinker-code/actions/workflows/ci-pythinker-cli.yml?query=branch%3Amain)
 
-[![PyPI downloads](https://assets.piptrends.com/get-last-month-downloads-badge/pythinker-code.svg)](https://piptrends.com/package/pythinker-code)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pythinker-code?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/pythinker-code)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-f59e0b.svg?style=flat-square&logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
 [![ACP ready](https://img.shields.io/badge/ACP-ready-7c3aed.svg?style=flat-square)](https://github.com/agentclientprotocol/agent-client-protocol)
 [![MCP tools](https://img.shields.io/badge/MCP-tools-0891b2.svg?style=flat-square)](https://modelcontextprotocol.io/)
@@ -115,15 +115,14 @@ It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientpr
 
 ---
 
-## 🆕 What's New in 0.31.0
+## 🆕 What's New in 0.32.0
 
-- **Release promotion no longer stalls when the Homebrew tap is broken.** The `promote-release` workflow now gates only on platform assets and PyPI; a lagging or broken Homebrew tap emits a warning annotation but no longer blocks the GitHub Release from reaching Latest.
-- **Calmer, theme-aligned TUI rendering.** Transcript, recap, and tool-header output now use theme-standardized activity colors, and Markdown tables render as a bordered grid (wide tables no longer collapse into a stacked-record list).
-- **Auto-mode tool approval fails closed when unattended.** In auto/non-interactive runs, actions still needing approval are denied with guidance instead of waiting indefinitely; the `auto_deliberate_destructive_actions` setting extends this backstop to interactive `--yolo` sessions.
-- **Yolo + auto mode hardened against silent over-reach.** Entering plan mode requires confirmation in interactive `--yolo` sessions; a new `--no-yolo` flag overrides yolo globally; resuming a yolo/auto session surfaces a startup warning.
-- **`pythinker review` validates finding evidence.** Reviewflow assembles prompts from a shared security-knowledge manifest and validates findings without failing the whole review on invalid ones.
+- **`pythinker mcp add` no longer crashes on Windows and Linux native builds.** `copy_metadata()` replaces the fragile `collect_data_files()` approach in all three PyInstaller specs, so `fastmcp` and `mcp` dist-info are bundled and `importlib.metadata` resolves correctly in frozen binaries.
+- **Pythinker work directories are automatically gitignored on startup.** `.pythinker/`, `.pythinker-review/`, and `.pythinker-review-flow/` are silently added to the project's `.gitignore` when the agent starts inside a git repo, keeping the working tree clean.
+- **Old sessions and plan files are swept on startup.** Archives older than `session_retention_days` (default 30) are removed non-interactively at launch. Set `session_retention_days = 0` to disable.
+- **Windows upgrade version display fix.** Inno Setup now wipes `_internal` before installing new files, so in-place upgrades no longer show a stale version number or re-trigger the update prompt.
 
-Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.31.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
+Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.32.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
 
 
 ---
@@ -213,7 +212,7 @@ matches your OS — no Python, Node, or `uv` prerequisite.
 
 | Platform | Recommended install | Artifact source |
 |---|---|---|
-| **🪟 Windows** | `irm https://pythinker.com/install.ps1 \| iex` | `PythinkerSetup-0.31.0.exe` from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
+| **🪟 Windows** | `irm https://pythinker.com/install.ps1 \| iex` | `PythinkerSetup-0.32.0.exe` from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
 | **<img src="https://img.shields.io/badge/-macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS"> / <img src="https://img.shields.io/badge/-Linux-FCC624?style=flat-square&logo=linux&logoColor=black" alt="Linux">** | `curl -fsSL https://pythinker.com/install.sh \| bash` | native tarball from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
 | **<img src="https://img.shields.io/badge/-macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS"> — Homebrew** | `brew install Pythoughts-labs/pythinker/pythinker-code` | auto-published Homebrew tap |
 | **🐳 Docker** | `docker run --rm -it ghcr.io/pythoughts-labs/pythinker-code` | GHCR multi-arch image |
@@ -241,7 +240,7 @@ pythinker                      # start the interactive TUI
 
 ### 🪟 Windows — native installer
 
-`PythinkerSetup-0.31.0.exe` is a signed* Inno Setup wizard. Installs per-user
+`PythinkerSetup-0.32.0.exe` is a signed* Inno Setup wizard. Installs per-user
 into `%LOCALAPPDATA%\Programs\Pythinker`, registers `pythinker` on your user
 PATH (`HKCU\Environment`), broadcasts `WM_SETTINGCHANGE` so new shells see
 the change. **No UAC prompt.**
@@ -252,13 +251,13 @@ irm https://pythinker.com/install.ps1 | iex
 
 # Or manually download the installer + checksum from the Releases page,
 # verify with Get-FileHash, then run:
-.\PythinkerSetup-0.31.0.exe
+.\PythinkerSetup-0.32.0.exe
 
 # Open a fresh PowerShell
 pythinker --version
 ```
 
-**Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.31.0.exe /ALLUSERS`
+**Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.32.0.exe /ALLUSERS`
 installs to `%ProgramFiles%\Pythinker` and writes PATH to HKLM (requires admin).
 
 **Upgrade:** `pythinker update` from inside the running app — it downloads
@@ -309,26 +308,26 @@ attached to every GitHub Release.
 
 ```sh
 # Debian / Ubuntu (x86_64)
-sudo dpkg -i pythinker-code_0.31.0_amd64.deb
+sudo dpkg -i pythinker-code_0.32.0_amd64.deb
 sudo apt-get install -f       # only if dpkg reports missing deps
 
 # Debian / Ubuntu (ARM64)
-sudo dpkg -i pythinker-code_0.31.0_arm64.deb
+sudo dpkg -i pythinker-code_0.32.0_arm64.deb
 
 # Fedora / RHEL / openSUSE (x86_64)
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.31.0/pythinker-code-0.31.0.x86_64.rpm
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.31.0/pythinker-code-0.31.0.x86_64.rpm.sha256
-sha256sum -c pythinker-code-0.31.0.x86_64.rpm.sha256
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.32.0/pythinker-code-0.32.0.x86_64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.32.0/pythinker-code-0.32.0.x86_64.rpm.sha256
+sha256sum -c pythinker-code-0.32.0.x86_64.rpm.sha256
 # Fedora / RHEL:
-sudo dnf install ./pythinker-code-0.31.0.x86_64.rpm
+sudo dnf install ./pythinker-code-0.32.0.x86_64.rpm
 # openSUSE:
-sudo zypper install ./pythinker-code-0.31.0.x86_64.rpm
+sudo zypper install ./pythinker-code-0.32.0.x86_64.rpm
 
 # Fedora / RHEL (aarch64)
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.31.0/pythinker-code-0.31.0.aarch64.rpm
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.31.0/pythinker-code-0.31.0.aarch64.rpm.sha256
-sha256sum -c pythinker-code-0.31.0.aarch64.rpm.sha256
-sudo dnf install ./pythinker-code-0.31.0.aarch64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.32.0/pythinker-code-0.32.0.aarch64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.32.0/pythinker-code-0.32.0.aarch64.rpm.sha256
+sha256sum -c pythinker-code-0.32.0.aarch64.rpm.sha256
+sudo dnf install ./pythinker-code-0.32.0.aarch64.rpm
 ```
 
 Both packages drop a small `/usr/bin/pythinker` launcher that execs the real
@@ -337,8 +336,8 @@ binary under `/usr/lib/pythinker/`, so your `$PATH` stays tidy.
 **Verify before install:**
 
 ```sh
-sha256sum -c pythinker-code_0.31.0_amd64.deb.sha256        # Debian/Ubuntu
-sha256sum -c pythinker-code-0.31.0.x86_64.rpm.sha256       # Fedora/RHEL
+sha256sum -c pythinker-code_0.32.0_amd64.deb.sha256        # Debian/Ubuntu
+sha256sum -c pythinker-code-0.32.0.x86_64.rpm.sha256       # Fedora/RHEL
 ```
 
 **Upgrade:** download the new `.deb`/`.rpm` from Releases and `dpkg -i` /

{pythinker_code-0.31.0 → pythinker_code-0.32.0}/README.md

@@ -14,7 +14,7 @@
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-16a34a.svg?style=for-the-badge)](https://github.com/Pythoughts-labs/pythinker-code/blob/main/LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/Pythoughts-labs/pythinker-code/ci-pythinker-cli.yml?branch=main&label=CI&style=for-the-badge&logo=githubactions&logoColor=white)](https://github.com/Pythoughts-labs/pythinker-code/actions/workflows/ci-pythinker-cli.yml?query=branch%3Amain)
 
-[![PyPI downloads](https://assets.piptrends.com/get-last-month-downloads-badge/pythinker-code.svg)](https://piptrends.com/package/pythinker-code)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/pythinker-code?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/pythinker-code)
 [![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-f59e0b.svg?style=flat-square&logo=ruff&logoColor=white)](https://docs.astral.sh/ruff/)
 [![ACP ready](https://img.shields.io/badge/ACP-ready-7c3aed.svg?style=flat-square)](https://github.com/agentclientprotocol/agent-client-protocol)
 [![MCP tools](https://img.shields.io/badge/MCP-tools-0891b2.svg?style=flat-square)](https://modelcontextprotocol.io/)
@@ -50,15 +50,14 @@ It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientpr
 
 ---
 
-## 🆕 What's New in 0.31.0
+## 🆕 What's New in 0.32.0
 
-- **Release promotion no longer stalls when the Homebrew tap is broken.** The `promote-release` workflow now gates only on platform assets and PyPI; a lagging or broken Homebrew tap emits a warning annotation but no longer blocks the GitHub Release from reaching Latest.
-- **Calmer, theme-aligned TUI rendering.** Transcript, recap, and tool-header output now use theme-standardized activity colors, and Markdown tables render as a bordered grid (wide tables no longer collapse into a stacked-record list).
-- **Auto-mode tool approval fails closed when unattended.** In auto/non-interactive runs, actions still needing approval are denied with guidance instead of waiting indefinitely; the `auto_deliberate_destructive_actions` setting extends this backstop to interactive `--yolo` sessions.
-- **Yolo + auto mode hardened against silent over-reach.** Entering plan mode requires confirmation in interactive `--yolo` sessions; a new `--no-yolo` flag overrides yolo globally; resuming a yolo/auto session surfaces a startup warning.
-- **`pythinker review` validates finding evidence.** Reviewflow assembles prompts from a shared security-knowledge manifest and validates findings without failing the whole review on invalid ones.
+- **`pythinker mcp add` no longer crashes on Windows and Linux native builds.** `copy_metadata()` replaces the fragile `collect_data_files()` approach in all three PyInstaller specs, so `fastmcp` and `mcp` dist-info are bundled and `importlib.metadata` resolves correctly in frozen binaries.
+- **Pythinker work directories are automatically gitignored on startup.** `.pythinker/`, `.pythinker-review/`, and `.pythinker-review-flow/` are silently added to the project's `.gitignore` when the agent starts inside a git repo, keeping the working tree clean.
+- **Old sessions and plan files are swept on startup.** Archives older than `session_retention_days` (default 30) are removed non-interactively at launch. Set `session_retention_days = 0` to disable.
+- **Windows upgrade version display fix.** Inno Setup now wipes `_internal` before installing new files, so in-place upgrades no longer show a stale version number or re-trigger the update prompt.
 
-Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.31.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
+Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.32.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
 
 
 ---
@@ -148,7 +147,7 @@ matches your OS — no Python, Node, or `uv` prerequisite.
 
 | Platform | Recommended install | Artifact source |
 |---|---|---|
-| **🪟 Windows** | `irm https://pythinker.com/install.ps1 \| iex` | `PythinkerSetup-0.31.0.exe` from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
+| **🪟 Windows** | `irm https://pythinker.com/install.ps1 \| iex` | `PythinkerSetup-0.32.0.exe` from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
 | **<img src="https://img.shields.io/badge/-macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS"> / <img src="https://img.shields.io/badge/-Linux-FCC624?style=flat-square&logo=linux&logoColor=black" alt="Linux">** | `curl -fsSL https://pythinker.com/install.sh \| bash` | native tarball from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
 | **<img src="https://img.shields.io/badge/-macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS"> — Homebrew** | `brew install Pythoughts-labs/pythinker/pythinker-code` | auto-published Homebrew tap |
 | **🐳 Docker** | `docker run --rm -it ghcr.io/pythoughts-labs/pythinker-code` | GHCR multi-arch image |
@@ -176,7 +175,7 @@ pythinker                      # start the interactive TUI
 
 ### 🪟 Windows — native installer
 
-`PythinkerSetup-0.31.0.exe` is a signed* Inno Setup wizard. Installs per-user
+`PythinkerSetup-0.32.0.exe` is a signed* Inno Setup wizard. Installs per-user
 into `%LOCALAPPDATA%\Programs\Pythinker`, registers `pythinker` on your user
 PATH (`HKCU\Environment`), broadcasts `WM_SETTINGCHANGE` so new shells see
 the change. **No UAC prompt.**
@@ -187,13 +186,13 @@ irm https://pythinker.com/install.ps1 | iex
 
 # Or manually download the installer + checksum from the Releases page,
 # verify with Get-FileHash, then run:
-.\PythinkerSetup-0.31.0.exe
+.\PythinkerSetup-0.32.0.exe
 
 # Open a fresh PowerShell
 pythinker --version
 ```
 
-**Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.31.0.exe /ALLUSERS`
+**Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.32.0.exe /ALLUSERS`
 installs to `%ProgramFiles%\Pythinker` and writes PATH to HKLM (requires admin).
 
 **Upgrade:** `pythinker update` from inside the running app — it downloads
@@ -244,26 +243,26 @@ attached to every GitHub Release.
 
 ```sh
 # Debian / Ubuntu (x86_64)
-sudo dpkg -i pythinker-code_0.31.0_amd64.deb
+sudo dpkg -i pythinker-code_0.32.0_amd64.deb
 sudo apt-get install -f       # only if dpkg reports missing deps
 
 # Debian / Ubuntu (ARM64)
-sudo dpkg -i pythinker-code_0.31.0_arm64.deb
+sudo dpkg -i pythinker-code_0.32.0_arm64.deb
 
 # Fedora / RHEL / openSUSE (x86_64)
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.31.0/pythinker-code-0.31.0.x86_64.rpm
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.31.0/pythinker-code-0.31.0.x86_64.rpm.sha256
-sha256sum -c pythinker-code-0.31.0.x86_64.rpm.sha256
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.32.0/pythinker-code-0.32.0.x86_64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.32.0/pythinker-code-0.32.0.x86_64.rpm.sha256
+sha256sum -c pythinker-code-0.32.0.x86_64.rpm.sha256
 # Fedora / RHEL:
-sudo dnf install ./pythinker-code-0.31.0.x86_64.rpm
+sudo dnf install ./pythinker-code-0.32.0.x86_64.rpm
 # openSUSE:
-sudo zypper install ./pythinker-code-0.31.0.x86_64.rpm
+sudo zypper install ./pythinker-code-0.32.0.x86_64.rpm
 
 # Fedora / RHEL (aarch64)
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.31.0/pythinker-code-0.31.0.aarch64.rpm
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.31.0/pythinker-code-0.31.0.aarch64.rpm.sha256
-sha256sum -c pythinker-code-0.31.0.aarch64.rpm.sha256
-sudo dnf install ./pythinker-code-0.31.0.aarch64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.32.0/pythinker-code-0.32.0.aarch64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.32.0/pythinker-code-0.32.0.aarch64.rpm.sha256
+sha256sum -c pythinker-code-0.32.0.aarch64.rpm.sha256
+sudo dnf install ./pythinker-code-0.32.0.aarch64.rpm
 ```
 
 Both packages drop a small `/usr/bin/pythinker` launcher that execs the real
@@ -272,8 +271,8 @@ binary under `/usr/lib/pythinker/`, so your `$PATH` stays tidy.
 **Verify before install:**
 
 ```sh
-sha256sum -c pythinker-code_0.31.0_amd64.deb.sha256        # Debian/Ubuntu
-sha256sum -c pythinker-code-0.31.0.x86_64.rpm.sha256       # Fedora/RHEL
+sha256sum -c pythinker-code_0.32.0_amd64.deb.sha256        # Debian/Ubuntu
+sha256sum -c pythinker-code-0.32.0.x86_64.rpm.sha256       # Fedora/RHEL
 ```
 
 **Upgrade:** download the new `.deb`/`.rpm` from Releases and `dpkg -i` /

{pythinker_code-0.31.0 → pythinker_code-0.32.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pythinker-code"
-version = "0.31.0"
+version = "0.32.0"
 description = "Pythinker Code is your next CLI agent."
 readme = "README.md"
 requires-python = ">=3.12"

{pythinker_code-0.31.0 → pythinker_code-0.32.0}/src/pythinker_code/CHANGELOG.md

@@ -15,6 +15,17 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+## 0.32.0 (2026-06-03)
+
+### What changed in this release
+
+- **`pythinker mcp add` no longer crashes on Windows and Linux native builds.** The PyInstaller specs were using `collect_data_files()` which silently omits the `fastmcp-*.dist-info/` sibling directory; fastmcp calls `importlib.metadata.version("fastmcp")` at import time, so every `mcp add` / `mcp list` invocation raised `PackageNotFoundError`. Switched all three specs (Windows installer, Linux installer, macOS/tarball) to `copy_metadata()` — the PyInstaller-standard hook for bundling dist-info.
+- **Pythinker work directories are automatically gitignored on startup.** When the agent starts inside a git repository, `.pythinker/`, `.pythinker-review/`, and `.pythinker-review-flow/` are silently appended to the project's `.gitignore` if missing, preventing local agent state from making the working tree dirty.
+- **Old sessions and plan files are swept on startup.** Archived session directories under `~/.pythinker/sessions/` and hero-name plan files under `~/.pythinker/plans/` older than `session_retention_days` (default 30) are removed non-interactively at startup. Set `session_retention_days = 0` to disable.
+- **Windows upgrade version display fix.** In-place upgrades no longer show a stale version number or re-trigger the update prompt. Inno Setup now wipes `_internal` before installing new files, preventing old `dist-info` directories from accumulating and causing `importlib.metadata` to report the previous version.
+
+Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.32.0`, or use the native installer for your OS (see the README install table).
+
 ## 0.31.0 (2026-06-02)
 
 ### What changed in this release

{pythinker_code-0.31.0 → pythinker_code-0.32.0}/src/pythinker_code/acp/session.py

@@ -215,7 +215,7 @@ class ACPSession:
                     case _:
                         pass
         except LLMNotSet as e:
-            logger.exception("LLM not set:")
+            logger.warning("LLM not set — user has no provider configured")
             raise acp.RequestError.auth_required() from e
         except LLMNotSupported as e:
             logger.exception("LLM not supported:")

{pythinker_code-0.31.0 → pythinker_code-0.32.0}/src/pythinker_code/cli/__init__.py

@@ -803,8 +803,20 @@ def pythinker(
                 render_scratchpad_section,
                 scratch_file_exists,
             )
+            from pythinker_code.session_cleanup import (
+                sweep_old_plans,
+                sweep_old_sessions,
+                sweep_stale_work_dirs,
+            )
 
             scratchpad_status = await ensure_git_excluded(work_dir)
+
+            # Sweep accumulated state on startup (best-effort, non-blocking).
+            # Mirrors Claude Code's cleanupPeriodDays=30 model.
+            _retention = config.session_retention_days if isinstance(config, Config) else 30
+            await asyncio.to_thread(sweep_old_sessions, _retention)
+            await asyncio.to_thread(sweep_old_plans, _retention)
+            await asyncio.to_thread(sweep_stale_work_dirs)
             scratch_exists_before_start = scratch_file_exists(work_dir)
             if scratchpad_status.available:
                 session_source = "resume" if resumed else "startup"

{pythinker_code-0.31.0 → pythinker_code-0.32.0}/src/pythinker_code/config.py

@@ -497,6 +497,15 @@ class Config(BaseModel):
             "Enable anonymous telemetry to help improve pythinker-code. Set to false to opt out."
         ),
     )
+    session_retention_days: int = Field(
+        default=30,
+        ge=0,
+        description=(
+            "Archived session directories in ~/.pythinker/sessions/ older than this many days "
+            "are removed on startup. Plan files older than this many days are also pruned. "
+            "0 disables cleanup."
+        ),
+    )
 
     @model_validator(mode="after")
     def validate_model(self) -> Self:

{pythinker_code-0.31.0 → pythinker_code-0.32.0}/src/pythinker_code/scratchpad.py

@@ -32,6 +32,11 @@ SESSION_SCRATCH_DIR_REL_PATH = ".pythinker/scratch"
 SESSION_SCRATCH_IGNORE_PATTERN = f"{SESSION_SCRATCH_DIR_REL_PATH}/*.md"
 _SESSION_SCRATCH_IGNORE_SAMPLE = f"{SESSION_SCRATCH_DIR_REL_PATH}/session.md"
 
+# Patterns written to the project .gitignore when the agent starts in a git repo.
+# These directories are local-only agent state and must never be committed.
+_GITIGNORE_ENTRIES = (".pythinker/", ".pythinker-review/", ".pythinker-review-flow/")
+_GITIGNORE_SECTION_HEADER = "# pythinker — local agent state (do not commit)"
+
 StatusReason = Literal[
     "available_non_git",
     "available_git_ignored",
@@ -337,6 +342,9 @@ async def ensure_git_excluded(
                 ignored=False,
             )
 
+        # Ensure pythinker work dirs are gitignored in the project before any files are created.
+        await _append_gitignore_entries(work_dir)
+
         for candidate in (SCRATCH_REL_PATH, _SESSION_SCRATCH_IGNORE_SAMPLE):
             tracked = await runner(["ls-files", "--error-unmatch", "--", candidate])
             if not tracked.ok:
@@ -429,6 +437,41 @@ def _exclude_lock(path: Path) -> Generator[None]:
         fh.close()
 
 
+async def _append_gitignore_entries(work_dir: HostPath) -> None:
+    """Best-effort: append pythinker work-dir patterns to work_dir/.gitignore if missing.
+
+    Called once at agent startup to prevent pythinker's local state directories
+    from making the project's git working tree dirty. Never raises.
+    """
+    gitignore_path = Path(str(work_dir)) / ".gitignore"
+    try:
+        await with_retries(lambda: asyncio.to_thread(_write_gitignore_entries, gitignore_path))
+    except Exception:
+        logger.debug("scratchpad .gitignore update failed")
+
+
+def _write_gitignore_entries(gitignore_path: Path) -> None:
+    try:
+        with _exclude_lock(gitignore_path):
+            existing = gitignore_path.read_text(encoding="utf-8") if gitignore_path.exists() else ""
+            existing_lines = {line.strip() for line in existing.splitlines()}
+            missing = [e for e in _GITIGNORE_ENTRIES if e not in existing_lines]
+            if not missing:
+                return
+            prefix = "" if not existing or existing.endswith("\n") else "\n"
+            with gitignore_path.open("a", encoding="utf-8") as fh:
+                if _GITIGNORE_SECTION_HEADER not in existing_lines:
+                    fh.write(f"{prefix}{_GITIGNORE_SECTION_HEADER}\n")
+                elif prefix:
+                    fh.write(prefix)
+                for entry in missing:
+                    fh.write(f"{entry}\n")
+    except OSError as exc:
+        if is_transient_oserror(exc):
+            raise TransientScratchpadError(str(exc)) from exc
+        raise
+
+
 @contextlib.contextmanager
 def _scratch_file_lock(fh: TextIO) -> Generator[None]:
     """Best-effort advisory lock on the scratch file itself (no extra git file)."""

pythinker_code-0.32.0/src/pythinker_code/session_cleanup.py

@@ -0,0 +1,260 @@
+"""Age-based cleanup for personal-scope session and plan state.
+
+Runs at agent startup to keep ~/.pythinker/ from growing unboundedly.
+Mirrors the design used by Claude Code (cleanupPeriodDays=30): on startup,
+directories/files older than the retention threshold are removed if they are
+safe to discard (archived sessions, old plan files).
+
+Never raises — every error is logged at DEBUG level and silently skipped.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import shutil
+import time
+from hashlib import md5 as _md5
+from pathlib import Path
+
+from pythinker_code.utils.logging import logger
+
+_SESSIONS_DIR_NAME = "sessions"
+_PLANS_DIR_NAME = "plans"
+_LOCAL_HOST = "local"
+
+
+# ---------------------------------------------------------------------------
+# Public sweep functions
+# ---------------------------------------------------------------------------
+
+
+def sweep_old_sessions(max_age_days: int, *, share_dir: Path | None = None) -> int:
+    """Remove archived session directories older than ``max_age_days`` days.
+
+    Only sessions explicitly marked ``archived=True`` in their ``state.json`` are
+    eligible. Active or unarchived sessions are never touched regardless of age.
+    Orphan directories (no ``state.json``) are removed if their mtime is old enough.
+
+    After removing a session directory the corresponding per-session scratchpad
+    file in the project's ``.pythinker/scratch/`` directory is also deleted
+    (best-effort; a missing project dir is silently skipped).
+
+    Returns the number of directories removed. Returns 0 when disabled (``max_age_days <= 0``).
+    """
+    if max_age_days <= 0:
+        return 0
+
+    from pythinker_code.share import get_share_dir
+
+    root = share_dir or get_share_dir()
+    sessions_root = root / _SESSIONS_DIR_NAME
+    if not sessions_root.is_dir():
+        return 0
+
+    cutoff = time.time() - max_age_days * 86_400.0
+    bucket_to_path = _load_bucket_path_map(root)
+    removed = 0
+
+    try:
+        buckets = list(sessions_root.iterdir())
+    except OSError:
+        return 0
+
+    for bucket in buckets:
+        if not bucket.is_dir():
+            continue
+        work_dir_path = bucket_to_path.get(bucket.name)
+        try:
+            session_dirs = list(bucket.iterdir())
+        except OSError:
+            continue
+        for session_dir in session_dirs:
+            if not session_dir.is_dir():
+                continue
+            try:
+                if _maybe_remove_session(session_dir, cutoff, work_dir_path=work_dir_path):
+                    removed += 1
+            except Exception:
+                logger.debug("session_cleanup: skipping {d}", d=session_dir.name)
+
+        # Prune the bucket itself if it is now empty.
+        try:
+            if not any(bucket.iterdir()):
+                bucket.rmdir()
+        except OSError:
+            pass
+
+    if removed:
+        logger.debug("session_cleanup: removed {n} old archived session(s)", n=removed)
+    return removed
+
+
+def sweep_old_plans(max_age_days: int, *, share_dir: Path | None = None) -> int:
+    """Remove plan markdown files older than ``max_age_days`` days.
+
+    Plan files are hero-name-slugged markdown files written to ~/.pythinker/plans/
+    for each planning session. They are ephemeral by nature and safe to prune once old.
+
+    Returns the number of files removed. Returns 0 when disabled (``max_age_days <= 0``).
+    """
+    if max_age_days <= 0:
+        return 0
+
+    from pythinker_code.share import get_share_dir
+
+    plans_dir = (share_dir or get_share_dir()) / _PLANS_DIR_NAME
+    if not plans_dir.is_dir():
+        return 0
+
+    cutoff = time.time() - max_age_days * 86_400.0
+    removed = 0
+
+    try:
+        plan_files = list(plans_dir.glob("*.md"))
+    except OSError:
+        return 0
+
+    for plan_file in plan_files:
+        try:
+            if plan_file.stat().st_mtime < cutoff:
+                plan_file.unlink(missing_ok=True)
+                removed += 1
+        except Exception:
+            logger.debug("session_cleanup: skipping plan {f}", f=plan_file.name)
+
+    if removed:
+        logger.debug("session_cleanup: removed {n} old plan file(s)", n=removed)
+    return removed
+
+
+def sweep_stale_work_dirs(*, share_dir: Path | None = None) -> int:
+    """Prune pythinker.json entries for paths that no longer exist and have no sessions.
+
+    An entry is removed only when both conditions hold:
+    - The work directory path does not exist on disk.
+    - The corresponding sessions bucket directory is absent or empty.
+
+    This prevents data loss for projects that have been moved or temporarily
+    unmounted while sessions still exist.
+
+    Returns the number of entries pruned.
+    """
+    from pythinker_code.metadata import WorkDirMeta, load_metadata, save_metadata
+    from pythinker_code.share import get_share_dir
+
+    root = share_dir or get_share_dir()
+    sessions_root = root / _SESSIONS_DIR_NAME
+
+    try:
+        metadata = load_metadata()
+    except Exception:
+        return 0
+
+    keep: list[WorkDirMeta] = []
+    pruned = 0
+    for wd in metadata.work_dirs:
+        if Path(wd.path).exists():
+            keep.append(wd)
+            continue
+        try:
+            hash_ = _md5(wd.path.encode("utf-8"), usedforsecurity=False).hexdigest()
+            bucket_name = hash_ if wd.host == _LOCAL_HOST else f"{wd.host}_{hash_}"
+            bucket_dir = sessions_root / bucket_name
+            has_sessions = bucket_dir.is_dir() and any(bucket_dir.iterdir())
+        except Exception:
+            has_sessions = True  # err on the side of keeping
+        if has_sessions:
+            keep.append(wd)
+        else:
+            pruned += 1
+
+    if pruned:
+        metadata.work_dirs = keep
+        try:
+            save_metadata(metadata)
+            logger.debug("session_cleanup: pruned {n} stale work_dir(s) from registry", n=pruned)
+        except Exception:
+            logger.debug("session_cleanup: failed to save pruned metadata")
+
+    return pruned
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _maybe_remove_session(
+    session_dir: Path, cutoff: float, *, work_dir_path: str | None = None
+) -> bool:
+    """Return True if the session directory was removed, False otherwise."""
+    from pythinker_code.session_state import load_session_state
+
+    state_file = session_dir / "state.json"
+
+    if not state_file.exists():
+        # Orphan dir with no state — safe to remove if old enough.
+        try:
+            if session_dir.stat().st_mtime < cutoff:
+                shutil.rmtree(session_dir, ignore_errors=True)
+                return True
+        except OSError:
+            pass
+        return False
+
+    state = load_session_state(session_dir)
+
+    if not state.archived:
+        return False
+
+    try:
+        reference: float = state.archived_at or state.wire_mtime or session_dir.stat().st_mtime
+    except OSError:
+        return False
+
+    if reference >= cutoff:
+        return False
+
+    shutil.rmtree(session_dir, ignore_errors=True)
+    if work_dir_path is not None:
+        _try_remove_scratchpad(work_dir_path, session_dir.name)
+    return True
+
+
+def _try_remove_scratchpad(work_dir_path: str, session_uuid: str) -> None:
+    """Best-effort: delete the per-session scratchpad file for a removed session."""
+    scratch_dir = Path(work_dir_path) / ".pythinker" / "scratch"
+    if not scratch_dir.is_dir():
+        return
+    short_id = _session_short_id(session_uuid)
+    for f in scratch_dir.glob(f"{short_id}-*.md"):
+        with contextlib.suppress(OSError):
+            f.unlink(missing_ok=True)
+
+
+def _session_short_id(session_uuid: str) -> str:
+    """Compute the 12-char slug used as the scratchpad filename prefix."""
+    text = "".join(c if c.isalnum() else "-" for c in session_uuid.lower())
+    while "--" in text:
+        text = text.replace("--", "-")
+    return text.strip("-")[:12].strip("-") or "session"
+
+
+def _load_bucket_path_map(share_dir: Path) -> dict[str, str]:
+    """Return a mapping of sessions bucket directory name → work_dir path string."""
+    from pythinker_code.metadata import load_metadata
+
+    try:
+        metadata = load_metadata()
+    except Exception:
+        return {}
+
+    result: dict[str, str] = {}
+    for wd in metadata.work_dirs:
+        try:
+            hash_ = _md5(wd.path.encode("utf-8"), usedforsecurity=False).hexdigest()
+            bucket = hash_ if wd.host == _LOCAL_HOST else f"{wd.host}_{hash_}"
+            result[bucket] = wd.path
+        except Exception:
+            pass
+    return result