android-agent-harness 0.27.6__tar.gz

android_agent_harness-0.27.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rabee Elkholy
+
+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.

android_agent_harness-0.27.6/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: android-agent-harness
+Version: 0.27.6
+Summary: Deterministic Android Engineering for the AI Era: Turn Any AI Assistant into an Uncompromising Senior Android Engineering Team.
+Author: Rabee Elkholy
+License: MIT License
+        
+        Copyright (c) 2026 Rabee Elkholy
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/rabee-elkholy/android-agent-harness
+Project-URL: Issues, https://github.com/rabee-elkholy/android-agent-harness/issues
+Keywords: android,kmp,ai-agents,code-review,governance,mcp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<div align="center">
+
+# android-agent-harness
+
+### Deterministic Android Engineering for the AI Era
+**Turn Any AI Assistant into an Uncompromising Senior Android Engineering Team.**
+
+[![CI Build](https://img.shields.io/github/actions/workflow/status/rabee-elkholy/android-agent-harness/ci.yml?branch=main&style=flat-square&label=CI%20Build)](https://github.com/rabee-elkholy/android-agent-harness/actions/workflows/ci.yml)
+[![Latest Release](https://img.shields.io/github/v/release/rabee-elkholy/android-agent-harness?color=2ea44f&style=flat-square&label=Release)](https://github.com/rabee-elkholy/android-agent-harness/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20KMP-3DDC84?style=flat-square)](https://android.com)
+[![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square)](https://python.org)
+[![Quality Gate](https://img.shields.io/badge/Quality%20Gate-6--Leaf%20Pass-success?style=flat-square)](docs/architecture.md)
+[![AI Tools](https://img.shields.io/badge/AI%20Tools-14%20IDs%20%7C%2011%20Templates-8A2BE2?style=flat-square)](docs/tool-support.md)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
+
+<br/><br/>
+<img src="docs/assets/banner.svg" alt="android-agent-harness: Deterministic Android Engineering for the AI Era" width="100%" />
+
+</div>
+
+---
+
+## Why the Harness? Prompts are Polite Requests. The Harness is an OS-Level Cage.
+
+Prompts, `.cursorrules`, and `SKILL.md` files decay as conversation context expands. AI coding assistants eventually hallucinate success, break Room migrations, ignore RTL layouts, and push unreviewed code.
+
+The **Android Agent Harness** enforces deterministic, cryptographic, and OS-level execution barriers outside the model brain:
+
+| Android Failure Mode | Bare AI Assistant | Android Agent Harness |
+| :--- | :--- | :--- |
+| **Room Migrations** | Modifies `@Entity` without migration -> app crashes on user upgrade. | **Room Guard (`room_guard.py`)**: Hard-blocks un-migrated Kotlin & Java entities. |
+| **Localization & RTL** | Hardcodes strings, drops Arabic (`values-ar`), scrambles placeholders. | **Adaptive String Guard (`check_strings.py`)**: Sub-second diff-scoped parity check. |
+| **ANR & Main-Thread I/O** | Runs disk/network I/O on `Dispatchers.Main`; leaks sensor listeners. | **Perf & ANR Guardian**: Enforces 60/120 FPS fluidity and lifecycle unregistration. |
+| **Review Verification** | Model declares "LGTM!" and assumes its own fix works. | **Cryptographic Barrier**: Assembly (`:assembleDebug`) locked until 6 guardians emit SHA-256 tokens. |
+| **Rogue Git Commits** | Runs `git commit` or `git push --force` to hide compilation mistakes. | **OS Interceptor (`pre_tool_safety.py`)**: Hard-denies unauthorized Git and ADB mutations. |
+| **Legacy Codebases** | Linters output 4,000 legacy errors, stalling delivery. | **Zero Legacy Penalty**: Diff-scoped AST lint (`fast_kt_lint.py`) inspects modified lines in <1s. |
+
+---
+
+### The Cage in Action: Real-Time Interceptions
+
+```text
+[MODEL ATTEMPTS] > git push --force origin main
+[HARNESS CAGE]   [DENIED] Autonomous git push is strictly blocked. Human developer authority is absolute.
+
+[MODEL ATTEMPTS] > python agents/scripts/run_gradle_task.py :app:assembleDebug
+[HARNESS CAGE]   [LOCKED] Cryptographic Review Barrier active. Missing pass tokens: [BUG_PASS, PERF_PASS].
+
+[PREFLIGHT GATE] python agents/scripts/room_guard.py
+[HARNESS CAGE]   [FAIL] Room database AppDatabase.kt version was NOT incremented. Destructive fallback banned.
+```
+
+---
+
+## The 6 Parallel Quality Guardians
+
+Before `:app:assembleDebug` or device deployment, 6 specialized subagents review the immutable snapshot in parallel:
+
+1. **`bug-reviewer-agent`** (`BUG_PASS`): Logic bugs, Kotlin null-safety across Java boundaries, and coroutine cancellation leaks.
+2. **`convention-reviewer-agent`** (`CONVENTION_PASS`): Clean Architecture, MVI StateFlow immutability, zero inline FQCNs.
+3. **`security-reviewer-agent`** (`SECURITY_PASS`): OWASP Mobile Top 10, unexported components, and credential isolation.
+4. **`perf-anr-guardian-agent`** (`PERF_PASS`): ANR elimination, Main-thread I/O prevention, and Compose recomposition fluidity.
+5. **`regression-impact-reviewer-agent`** (`REGRESSION_PASS`): Blast radius analysis, caller graph impacts, and API signature changes.
+6. **`test-quality-reviewer-agent`** (`TEST_PASS`): **Smart Test Promotion** — automatically promoted on test/mock diffs to verify assertion depth and `runTest` dispatchers.
+
+*On-demand specialists:* `qa-diagnostics-agent` (Logcat crash forensics) & `android-ui-expert-agent` (Compose & RTL layouts).
+
+---
+
+## Physical Device Verification & Interactive Sign-off
+
+Software that compiles is not necessarily software that works on mobile. The harness:
+1. Resolves connected physical devices via ADB (prioritizing physical devices over emulators).
+2. Builds and installs via `run_device.py install-start`, launching the target Activity directly.
+3. Generates **2 to 3 diff-grounded manual test steps** and triggers an interactive confirmation modal (`ask_question`):
+   `PASS -- Device testing passed successfully` vs `FAIL -- Issue or crash encountered`.
+
+---
+
+## Quickstart in 60 Seconds
+
+### Option A: Via AI Chat Prompt (Recommended)
+Open a new chat session in your AI assistant (Antigravity, Claude Code, Cursor, Copilot, Windsurf) at your project root and paste:
+
+```text
+Read https://raw.githubusercontent.com/rabee-elkholy/android-agent-harness/v0.27.6/docs/install-or-update-prompt.md and follow all its instructions.
+```
+
+### Option B: Via Terminal CLI
+```bash
+pipx install git+https://github.com/rabee-elkholy/android-agent-harness.git
+android-harness init
+```
+
+---
+
+## Supported AI Environments (14 Tools, 3 Tiers)
+
+* **Hook-Enforced**: Google Antigravity, Claude Code, GitHub Copilot (deterministic Python OS-level interceptors).
+* **Rule-Driven**: Cursor, Windsurf, Cline, Roo Code, Amazon Q, Continue, Junie, Kilo, Goose, Qwen, Codex.
+* **Prompt-Only**: Aider, Zed, Devin, Amp, Factory, Jules, Warp, OpenCode (`AGENTS.md` standard).
+
+---
+
+## Documentation & Deep-Dives
+
+* **[Architecture Guide](docs/architecture.md)**: 7-stage delivery lifecycle, safety interceptor mechanics, and preflight pipeline.
+* **[Developer Workflows](docs/workflows.md)**: 10 structured engineering playbooks (TDD, forensic triage, ANR audit, preflight).
+* **[Quickstart & CLI](docs/quickstart.md)**: Complete CLI command matrix and environment setup.
+* **[Threat Model & Security](docs/threat-model.md)**: Analysis of 7 threat vectors and mitigation layers.
+* **[Architecture Decision Records (ADRs)](docs/adr/)**: Formal ADRs (001-006) covering review gates, human git authority, and conflict adjudication.
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for details.

android_agent_harness-0.27.6/README.md

@@ -0,0 +1,118 @@
+<div align="center">
+
+# android-agent-harness
+
+### Deterministic Android Engineering for the AI Era
+**Turn Any AI Assistant into an Uncompromising Senior Android Engineering Team.**
+
+[![CI Build](https://img.shields.io/github/actions/workflow/status/rabee-elkholy/android-agent-harness/ci.yml?branch=main&style=flat-square&label=CI%20Build)](https://github.com/rabee-elkholy/android-agent-harness/actions/workflows/ci.yml)
+[![Latest Release](https://img.shields.io/github/v/release/rabee-elkholy/android-agent-harness?color=2ea44f&style=flat-square&label=Release)](https://github.com/rabee-elkholy/android-agent-harness/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20KMP-3DDC84?style=flat-square)](https://android.com)
+[![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square)](https://python.org)
+[![Quality Gate](https://img.shields.io/badge/Quality%20Gate-6--Leaf%20Pass-success?style=flat-square)](docs/architecture.md)
+[![AI Tools](https://img.shields.io/badge/AI%20Tools-14%20IDs%20%7C%2011%20Templates-8A2BE2?style=flat-square)](docs/tool-support.md)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](CONTRIBUTING.md)
+
+<br/><br/>
+<img src="docs/assets/banner.svg" alt="android-agent-harness: Deterministic Android Engineering for the AI Era" width="100%" />
+
+</div>
+
+---
+
+## Why the Harness? Prompts are Polite Requests. The Harness is an OS-Level Cage.
+
+Prompts, `.cursorrules`, and `SKILL.md` files decay as conversation context expands. AI coding assistants eventually hallucinate success, break Room migrations, ignore RTL layouts, and push unreviewed code.
+
+The **Android Agent Harness** enforces deterministic, cryptographic, and OS-level execution barriers outside the model brain:
+
+| Android Failure Mode | Bare AI Assistant | Android Agent Harness |
+| :--- | :--- | :--- |
+| **Room Migrations** | Modifies `@Entity` without migration -> app crashes on user upgrade. | **Room Guard (`room_guard.py`)**: Hard-blocks un-migrated Kotlin & Java entities. |
+| **Localization & RTL** | Hardcodes strings, drops Arabic (`values-ar`), scrambles placeholders. | **Adaptive String Guard (`check_strings.py`)**: Sub-second diff-scoped parity check. |
+| **ANR & Main-Thread I/O** | Runs disk/network I/O on `Dispatchers.Main`; leaks sensor listeners. | **Perf & ANR Guardian**: Enforces 60/120 FPS fluidity and lifecycle unregistration. |
+| **Review Verification** | Model declares "LGTM!" and assumes its own fix works. | **Cryptographic Barrier**: Assembly (`:assembleDebug`) locked until 6 guardians emit SHA-256 tokens. |
+| **Rogue Git Commits** | Runs `git commit` or `git push --force` to hide compilation mistakes. | **OS Interceptor (`pre_tool_safety.py`)**: Hard-denies unauthorized Git and ADB mutations. |
+| **Legacy Codebases** | Linters output 4,000 legacy errors, stalling delivery. | **Zero Legacy Penalty**: Diff-scoped AST lint (`fast_kt_lint.py`) inspects modified lines in <1s. |
+
+---
+
+### The Cage in Action: Real-Time Interceptions
+
+```text
+[MODEL ATTEMPTS] > git push --force origin main
+[HARNESS CAGE]   [DENIED] Autonomous git push is strictly blocked. Human developer authority is absolute.
+
+[MODEL ATTEMPTS] > python agents/scripts/run_gradle_task.py :app:assembleDebug
+[HARNESS CAGE]   [LOCKED] Cryptographic Review Barrier active. Missing pass tokens: [BUG_PASS, PERF_PASS].
+
+[PREFLIGHT GATE] python agents/scripts/room_guard.py
+[HARNESS CAGE]   [FAIL] Room database AppDatabase.kt version was NOT incremented. Destructive fallback banned.
+```
+
+---
+
+## The 6 Parallel Quality Guardians
+
+Before `:app:assembleDebug` or device deployment, 6 specialized subagents review the immutable snapshot in parallel:
+
+1. **`bug-reviewer-agent`** (`BUG_PASS`): Logic bugs, Kotlin null-safety across Java boundaries, and coroutine cancellation leaks.
+2. **`convention-reviewer-agent`** (`CONVENTION_PASS`): Clean Architecture, MVI StateFlow immutability, zero inline FQCNs.
+3. **`security-reviewer-agent`** (`SECURITY_PASS`): OWASP Mobile Top 10, unexported components, and credential isolation.
+4. **`perf-anr-guardian-agent`** (`PERF_PASS`): ANR elimination, Main-thread I/O prevention, and Compose recomposition fluidity.
+5. **`regression-impact-reviewer-agent`** (`REGRESSION_PASS`): Blast radius analysis, caller graph impacts, and API signature changes.
+6. **`test-quality-reviewer-agent`** (`TEST_PASS`): **Smart Test Promotion** — automatically promoted on test/mock diffs to verify assertion depth and `runTest` dispatchers.
+
+*On-demand specialists:* `qa-diagnostics-agent` (Logcat crash forensics) & `android-ui-expert-agent` (Compose & RTL layouts).
+
+---
+
+## Physical Device Verification & Interactive Sign-off
+
+Software that compiles is not necessarily software that works on mobile. The harness:
+1. Resolves connected physical devices via ADB (prioritizing physical devices over emulators).
+2. Builds and installs via `run_device.py install-start`, launching the target Activity directly.
+3. Generates **2 to 3 diff-grounded manual test steps** and triggers an interactive confirmation modal (`ask_question`):
+   `PASS -- Device testing passed successfully` vs `FAIL -- Issue or crash encountered`.
+
+---
+
+## Quickstart in 60 Seconds
+
+### Option A: Via AI Chat Prompt (Recommended)
+Open a new chat session in your AI assistant (Antigravity, Claude Code, Cursor, Copilot, Windsurf) at your project root and paste:
+
+```text
+Read https://raw.githubusercontent.com/rabee-elkholy/android-agent-harness/v0.27.6/docs/install-or-update-prompt.md and follow all its instructions.
+```
+
+### Option B: Via Terminal CLI
+```bash
+pipx install git+https://github.com/rabee-elkholy/android-agent-harness.git
+android-harness init
+```
+
+---
+
+## Supported AI Environments (14 Tools, 3 Tiers)
+
+* **Hook-Enforced**: Google Antigravity, Claude Code, GitHub Copilot (deterministic Python OS-level interceptors).
+* **Rule-Driven**: Cursor, Windsurf, Cline, Roo Code, Amazon Q, Continue, Junie, Kilo, Goose, Qwen, Codex.
+* **Prompt-Only**: Aider, Zed, Devin, Amp, Factory, Jules, Warp, OpenCode (`AGENTS.md` standard).
+
+---
+
+## Documentation & Deep-Dives
+
+* **[Architecture Guide](docs/architecture.md)**: 7-stage delivery lifecycle, safety interceptor mechanics, and preflight pipeline.
+* **[Developer Workflows](docs/workflows.md)**: 10 structured engineering playbooks (TDD, forensic triage, ANR audit, preflight).
+* **[Quickstart & CLI](docs/quickstart.md)**: Complete CLI command matrix and environment setup.
+* **[Threat Model & Security](docs/threat-model.md)**: Analysis of 7 threat vectors and mitigation layers.
+* **[Architecture Decision Records (ADRs)](docs/adr/)**: Formal ADRs (001-006) covering review gates, human git authority, and conflict adjudication.
+
+---
+
+## License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for details.

android_agent_harness-0.27.6/agents/mcp/zoho_sprints/README.md

@@ -0,0 +1,26 @@
+# Zoho Sprints MCP
+
+Stdio MCP server. Same tools and mutate rules as the original engine (`update zoho`, Arabic templates, `In progress` / `Ready To ReTest`). Playbook: `../../workflows/zoho-sprints.md`.
+
+The kit ships **code + empty workflow defaults**, not tokens.
+
+Credentials stay on the developer's machine:
+
+1. Copy `config.example.json` to `~/.android-harness/zoho_sprints.json`
+2. Fill `client_id`, `client_secret`, `refresh_token`, `team_id`, `project_id`
+3. Never put that file in the app repo or in this kit
+
+To get Zoho API credentials:
+
+1. Go to https://api-console.zoho.com/ and create a **Self Client**
+2. Generate a grant token with scope: `ZohoSprints.sprints.ALL,ZohoSprints.items.ALL,ZohoSprints.team.READ`
+3. Exchange the grant token for a refresh token using the Zoho OAuth endpoint
+4. Find your `team_id` and `project_id` from your Zoho Sprints URL: `https://sprints.zoho.com/team/<team_id>/project/<project_id>/...`
+
+`workflow_defaults.json` has assignee / item-prefix / title-strip settings. Empty values are resolved at runtime by the server. Fill them during install (I.16) or configure later.
+
+Setup (`I.16`) wires `.agents/mcp_config.json` (and Cursor `.cursor/mcp.json` when Cursor was selected) to this `server.py` and sets `ZOHO_SPRINTS_CONFIG` to an **existing** user file if one is already on the PC. It does not copy tokens.
+
+If a config already exists at `~/.gemini/antigravity/scratch/zoho_sprints/zoho_config.json`, setup points at that path and leaves the file untouched.
+
+Zoho Desk is not included.

android_agent_harness-0.27.6/agents/mcp/zoho_sprints/_client.py

@@ -0,0 +1,304 @@
+"""Zoho Sprints API client, OAuth authentication, caching and endpoints."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from _formatter import format_zoho_html
+
+HERE = Path(__file__).resolve().parent
+
+WORKFLOW_KEYS = (
+    "team_id",
+    "project_id",
+    "default_user_id",
+    "item_prefix",
+    "title_strip_suffixes",
+    "fallback_item_type_id",
+    "fallback_priority_id",
+    "fallback_sprint_id",
+)
+
+
+def _workflow_defaults() -> dict:
+    path = HERE / "workflow_defaults.json"
+    if not path.is_file():
+        return {}
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return data if isinstance(data, dict) else {}
+
+
+class ZohoSprintsAPI:
+    METADATA_CACHE_TTL = 300
+
+    def __init__(self, config_path: str):
+        self.config_path = config_path
+        self._meta_cache: dict[str, tuple[float, dict]] = {}
+        self.base_url = "https://sprintsapi.zoho.com/zsapi"
+        self.load_config()
+
+    def load_config(self) -> None:
+        with open(self.config_path, encoding="utf-8") as f:
+            user = json.load(f)
+        if not isinstance(user, dict):
+            raise RuntimeError("Zoho Sprints config must be a JSON object.")
+        defaults = _workflow_defaults()
+        self.config = dict(user)
+        for key in WORKFLOW_KEYS:
+            if key not in user or user.get(key) in (None, "", []):
+                if key in defaults:
+                    self.config[key] = defaults[key]
+        self.access_token = user.get("access_token")
+        self.refresh_token = user.get("refresh_token")
+        self.client_id = user.get("client_id")
+        self.client_secret = user.get("client_secret")
+        self.auth_domain = user.get("auth_domain") or "https://accounts.zoho.com"
+        self.team_id = str(self.config.get("team_id") or "").strip()
+        self.project_id = str(self.config.get("project_id") or "").strip()
+        self.default_user_id = str(self.config.get("default_user_id") or "").strip()
+        self.item_prefix = str(self.config.get("item_prefix") or "").strip()
+        self.fallback_item_type_id = str(self.config.get("fallback_item_type_id") or "").strip()
+        self.fallback_priority_id = str(self.config.get("fallback_priority_id") or "").strip()
+        self.fallback_sprint_id = str(self.config.get("fallback_sprint_id") or "").strip()
+        suffixes = self.config.get("title_strip_suffixes") or []
+        self.title_strip_suffixes = [str(s) for s in suffixes if str(s).strip()]
+        if not self.team_id or not self.project_id:
+            raise RuntimeError("Zoho Sprints config needs team_id and project_id.")
+
+    def save_config(self) -> None:
+        path = Path(self.config_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            if hasattr(os, "O_CREAT") and os.name != "nt":
+                fd = os.open(str(path), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+                with open(fd, "w", encoding="utf-8") as f:
+                    json.dump(self.config, f, indent=2)
+            else:
+                with open(self.config_path, "w", encoding="utf-8") as f:
+                    json.dump(self.config, f, indent=2)
+        except Exception:
+            with open(self.config_path, "w", encoding="utf-8") as f:
+                json.dump(self.config, f, indent=2)
+
+    def sanitize_task_name(self, name: str) -> str:
+        cleaned = name.strip()
+        for suffix in self.title_strip_suffixes:
+            cleaned = re.sub(
+                r"\s*[-–—]\s*" + re.escape(suffix) + r"\s*$",
+                "",
+                cleaned,
+                flags=re.IGNORECASE,
+            ).strip()
+        return cleaned
+
+    def refresh_token_if_needed(self) -> None:
+        url = f"{self.auth_domain}/oauth/v2/token"
+        params = {
+            "refresh_token": self.refresh_token,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "grant_type": "refresh_token",
+        }
+        encoded = urllib.parse.urlencode(params).encode("utf-8")
+        req = urllib.request.Request(url, data=encoded, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=30.0) as resp:
+                res = json.loads(resp.read().decode("utf-8"))
+        except Exception as e:
+            raise RuntimeError(f"Zoho OAuth token refresh network error: {e}") from e
+        if "access_token" in res:
+            self.access_token = res["access_token"]
+            self.config["access_token"] = self.access_token
+            self.save_config()
+        else:
+            err = res.get("error", "unknown_oauth_error")
+            raise RuntimeError(f"Zoho OAuth token refresh failed: {err}. Re-authenticate in config.")
+
+    def _request(self, path: str, method: str = "GET", params: dict | None = None, data: dict | None = None) -> Any:
+        url = f"{self.base_url}{path}"
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        headers = {"Authorization": f"Zoho-oauthtoken {self.access_token}"}
+        encoded_data = None
+        if data is not None:
+            encoded_data = urllib.parse.urlencode(data).encode("utf-8")
+            headers["Content-Type"] = "application/x-www-form-urlencoded"
+
+        max_retries = 3
+        for attempt in range(max_retries):
+            req = urllib.request.Request(url, data=encoded_data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=30.0) as resp:
+                    return json.loads(resp.read().decode("utf-8"))
+            except urllib.error.HTTPError as exc:
+                err_msg = exc.read().decode("utf-8", errors="replace")
+                if exc.code in (429, 502, 503, 504) and attempt < max_retries - 1:
+                    time.sleep(1.0 * (attempt + 1))
+                    continue
+                if exc.code == 401 or "Invalid oauthToken" in err_msg or "invalid_token" in err_msg:
+                    self.refresh_token_if_needed()
+                    headers["Authorization"] = f"Zoho-oauthtoken {self.access_token}"
+                    req2 = urllib.request.Request(url, data=encoded_data, headers=headers, method=method)
+                    try:
+                        with urllib.request.urlopen(req2, timeout=30.0) as resp2:
+                            return json.loads(resp2.read().decode("utf-8"))
+                    except Exception as retry_exc:
+                        raise RuntimeError(f"Zoho request failed after token refresh: {retry_exc}") from retry_exc
+                raise RuntimeError(f"HTTP Error {exc.code}: {err_msg}") from exc
+            except Exception as exc:
+                if attempt < max_retries - 1 and isinstance(exc, (urllib.error.URLError, TimeoutError)):
+                    time.sleep(1.0 * (attempt + 1))
+                    continue
+                raise RuntimeError(f"Zoho request failed ({method} {path}): {exc}") from exc
+
+    def get_sprints(self) -> dict:
+        return self._request(
+            f"/team/{self.team_id}/projects/{self.project_id}/sprints/",
+            params={"action": "data", "type": "[1,2,3,4]"},
+        )
+
+    def get_active_sprint_id(self) -> str:
+        ids = self.get_sprints().get("sprintIds") or []
+        if ids:
+            return ids[0]
+        if self.fallback_sprint_id:
+            return self.fallback_sprint_id
+        raise RuntimeError("No sprints found for this Zoho project.")
+
+    def _cached_request(self, cache_key: str, path: str, params: dict | None = None) -> dict:
+        cached = self._meta_cache.get(cache_key)
+        if cached:
+            ts, data = cached
+            if time.time() - ts < self.METADATA_CACHE_TTL:
+                return data
+        result = self._request(path, params=params)
+        self._meta_cache[cache_key] = (time.time(), result)
+        return result
+
+    def get_item_types(self) -> dict:
+        return self._cached_request(
+            "item_types",
+            f"/team/{self.team_id}/projects/{self.project_id}/itemtype/",
+            params={"action": "data"},
+        )
+
+    def get_statuses(self) -> dict:
+        return self._cached_request(
+            "statuses",
+            f"/team/{self.team_id}/projects/{self.project_id}/itemstatus/",
+            params={"action": "data"},
+        )
+
+    def get_priorities(self) -> dict:
+        return self._cached_request(
+            "priorities",
+            f"/team/{self.team_id}/projects/{self.project_id}/priority/",
+            params={"action": "data"},
+        )
+
+    def list_items(self, sprint_id: str) -> dict:
+        return self._request(
+            f"/team/{self.team_id}/projects/{self.project_id}/sprints/{sprint_id}/item/",
+            params={"action": "sprintitems", "subitem": "true"},
+        )
+
+    def resolve_item(self, item_input: str, sprint_id: str | None = None) -> tuple[str, str]:
+        raw_input = str(item_input).strip()
+        match = re.search(r"(\d+)", raw_input)
+        target_num = match.group(1) if match else raw_input
+        sprint_ids = self.get_sprints().get("sprintIds") or []
+        if len(raw_input) >= 15 and raw_input.isdigit():
+            if sprint_id:
+                return sprint_id, raw_input
+            for sid in sprint_ids:
+                try:
+                    res = self.get_item_details(sid, raw_input)
+                    if res.get("status") == "success":
+                        return sid, raw_input
+                except Exception:
+                    continue
+        search_sprints = [sprint_id] if sprint_id else sprint_ids
+        prefix = self.item_prefix
+        for sid in search_sprints:
+            items_data = self.list_items(sid)
+            item_prop = items_data.get("item_prop") or {}
+            item_no_idx = item_prop.get("itemNo")
+            item_jobj = items_data.get("itemJObj") or {}
+            for iid, row in item_jobj.items():
+                if iid == raw_input:
+                    return sid, iid
+                if item_no_idx is not None and len(row) > item_no_idx:
+                    item_no = str(row[item_no_idx])
+                    labels = {item_no, f"I{item_no}", target_num}
+                    if prefix:
+                        labels.add(f"{prefix}{item_no}")
+                    if raw_input in labels or item_no == target_num:
+                        return sid, iid
+        raise RuntimeError(
+            f"Item '{raw_input}' not found in {len(search_sprints)} sprint(s). "
+            "Verify the task id or pass sprint_id."
+        )
+
+    def get_item_details(self, sprint_id: str | None = None, item_id: str | None = None) -> dict:
+        if not sprint_id or (item_id and (not str(item_id).isdigit() or len(str(item_id)) < 15)):
+            sprint_id, item_id = self.resolve_item(item_id or sprint_id or "", sprint_id)
+        return self._request(
+            f"/team/{self.team_id}/projects/{self.project_id}/sprints/{sprint_id}/item/{item_id}/",
+            params={"action": "details"},
+        )
+
+    def create_item(
+        self,
+        sprint_id: str,
+        name: str,
+        item_type_id: str,
+        priority_id: str,
+        description: str = "",
+        points: str = "0",
+        parent_item_id: str | None = None,
+        users: list | None = None,
+    ) -> dict:
+        data: dict[str, str] = {
+            "name": self.sanitize_task_name(name),
+            "projitemtypeid": item_type_id,
+            "projpriorityid": priority_id,
+            "description": format_zoho_html(description),
+        }
+        assigned = users if users is not None else ([self.default_user_id] if self.default_user_id else None)
+        if assigned:
+            data["users"] = json.dumps(assigned)
+        if points and points != "0":
+            data["points"] = points
+        if parent_item_id:
+            path = f"/team/{self.team_id}/projects/{self.project_id}/sprints/{sprint_id}/item/{parent_item_id}/subitem/"
+        else:
+            path = f"/team/{self.team_id}/projects/{self.project_id}/sprints/{sprint_id}/item/"
+        return self._request(path, method="POST", data=data)
+
+    def update_item_status(self, sprint_id: str, item_id: str, status_id: str) -> dict:
+        return self._request(
+            f"/team/{self.team_id}/projects/{self.project_id}/sprints/{sprint_id}/item/{item_id}/",
+            method="POST",
+            data={"statusid": status_id},
+        )
+
+    def update_item_description(self, sprint_id: str, item_id: str, description: str) -> dict:
+        return self._request(
+            f"/team/{self.team_id}/projects/{self.project_id}/sprints/{sprint_id}/item/{item_id}/",
+            method="POST",
+            data={"description": format_zoho_html(description)},
+        )
+
+    def add_comment(self, sprint_id: str, item_id: str, content: str) -> dict:
+        return self._request(
+            f"/team/{self.team_id}/projects/{self.project_id}/sprints/{sprint_id}/item/{item_id}/notes/",
+            method="POST",
+            data={"name": format_zoho_html(content)},
+        )