task-harbor 0.7.0__tar.gz

task_harbor-0.7.0/LICENSE

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

task_harbor-0.7.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: task-harbor
+Version: 0.7.0
+Summary: Claude and GPT backlog orchestrator for planning, implementation, QA, escalation, and periodic code review.
+Author: rhit-nayeems
+License-Expression: MIT
+Project-URL: Repository, https://github.com/rhit-nayeems/task-harbor
+Project-URL: Issues, https://github.com/rhit-nayeems/task-harbor/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual<2,>=1
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Provides-Extra: ui
+Requires-Dist: textual<2,>=1; extra == "ui"
+Dynamic: license-file
+
+# Task Harbor
+
+Task Harbor is a command-line tool that runs coding tasks with Claude Code or
+Codex. It reads a Markdown backlog, plans each task, makes changes in separate
+Git worktrees, and checks the results before merging them into a local branch.
+
+It does not push changes or merge them into your original branch. You review the
+result on `manager/integration/<run-id>`.
+
+## Check the work before accepting it
+
+Configure tests once, then inspect the exact commands, checkpoint, and full diff
+for each task. Task agreements capture scope and unanswered questions. A failed
+check stops approval; a missing environment pauses work before more model calls.
+
+- [Set up checks and task agreements](docs/VERIFICATION.md)
+- [Compare Harbor with a direct agent](EVALUATION.md)
+
+```sh
+task-harbor preflight
+task-harbor review --run-id RUN_ID --html review.html
+```
+
+In the dashboard, press **E** for task evidence or **P** for suggested checks.
+
+## Install
+
+You need Python 3.11+, Git, and either Claude Code or Codex installed and signed in.
+The repository you want to work on must have at least one commit and a configured
+Git author.
+
+Install the Python package directly from this repository (no clone required):
+
+```sh
+python -m pip install "git+https://github.com/rhit-nayeems/task-harbor.git"
+task-harbor --version
+task-harbor guide
+```
+
+The dashboard is included. This project is not published to PyPI yet; do not use
+`pip install task-harbor` expecting this repository's package.
+
+<details>
+<summary>Isolated install, upgrades, and command-not-found fixes</summary>
+
+With pipx installed, use an isolated application environment:
+
+```sh
+pipx install "git+https://github.com/rhit-nayeems/task-harbor.git"
+pipx ensurepath
+```
+
+Restart your terminal after changing PATH. For a regular pip installation,
+`python -m task_harbor` works with the same arguments if the executable is not
+on PATH. Use the same Python interpreter you installed with.
+
+Upgrade a pip installation:
+
+```sh
+python -m pip install --upgrade "git+https://github.com/rhit-nayeems/task-harbor.git"
+```
+
+For pipx, use `pipx upgrade task-harbor`. Uninstall with `python -m pip uninstall
+task-harbor` or `pipx uninstall task-harbor`, respectively.
+
+</details>
+
+[First run](#start-a-run) · [Commands](#cli-commands) · [Configuration](docs/CONFIGURATION.md)
+
+## Terminal dashboard
+
+![Task dashboard with sample data](docs/terminal-dashboard.svg)
+
+<details>
+<summary>See first-run setup and built-in help</summary>
+
+![First-run screen](docs/terminal-welcome.svg)
+![Built-in help screen](docs/terminal-help.svg)
+![Task evidence screen with sample data](docs/terminal-evidence.svg)
+
+</details>
+
+These are captures of the actual terminal interface. The task dashboard uses
+sample run data. Open it inside your project:
+
+```sh
+task-harbor
+```
+
+Running `task-harbor` (or `python -m task_harbor`) without a command opens the
+dashboard for the current directory. `--help` lists the other commands.
+
+The dashboard shows saved runs, task status, dependencies, recent events, agent
+calls, and reported costs. Select a run with the picker and use the arrow keys
+to inspect tasks. Tab changes panes, F1 opens help, `r` refreshes, and `q` exits. It also
+refreshes automatically every two seconds.
+
+A run is one execution of your backlog. The run picker appears only after a run
+exists in the selected project.
+
+Use **Set up** to create the configuration and sample backlog, edit those files,
+then click **Validate**. **New run** and **Resume** show the provider, model, and
+call limit before you confirm agent work. **Stop** requests a pause after current
+calls finish. Closing the dashboard does not stop a launched run.
+
+Viewing progress does not consume tokens. Starting or resuming work does.
+Launch output is saved in `.manager/launch-logs/` (or your configured manager
+directory). Launch errors appear above the task list. Unreported costs are unknown.
+Use `tui --run-id <id>` to open a specific saved run. All commands below still work
+without the dashboard.
+
+## Start a run
+
+Replace `path/to/your-app` with the repository you want Task Harbor to work on.
+Use `--repo` before the command.
+
+```sh
+task-harbor --repo "path/to/your-app" init
+```
+
+This creates `.manager/config.json` and a sample `BACKLOG.md` in that repository.
+An existing backlog is kept. Replace the sample task with your own work:
+
+```markdown
+## BUG-001 — Fix empty search results
+- **Priority:** critical_bug
+- **Status:** UNPLANNED
+- **Dependencies:** —
+- **Acceptance criteria:**
+  - An empty search shows a message instead of crashing
+  - Existing search tests pass
+- **Next action:** Plan the task
+```
+
+Use a different ID for each task. List dependency IDs separated by commas.
+See [BACKLOG.example.md](BACKLOG.example.md) for a longer example.
+
+### Choose Claude or GPT
+
+Edit `.manager/config.json` before starting. Claude is the default:
+
+```json
+{
+  "provider": "claude",
+  "model": "opus",
+  "effort": "medium"
+}
+```
+
+For GPT, sign in with `codex login` and change these fields:
+
+```json
+{
+  "provider": "codex",
+  "model": "gpt-6.1-sol",
+  "effort": "medium",
+  "max_run_cost_usd": null,
+  "max_call_cost_usd": null
+}
+```
+
+Use a model available to your account. Provider choice applies to the whole run;
+you cannot switch providers when resuming it.
+
+### Set checks and limits
+
+Add your project's test or build commands to the configuration. For example:
+
+```json
+{
+  "verification_commands": ["python -m pytest"],
+  "max_agent_calls": 100,
+  "max_task_agent_calls": 20
+}
+```
+
+These call limits are examples; the defaults are unlimited. Both providers support
+call limits and timeouts. Only Claude supports estimated dollar caps. Codex
+requires both dollar-budget settings to be `null`.
+
+Now validate the backlog, check the selected agent, and start:
+
+```sh
+task-harbor --repo "path/to/your-app" validate
+task-harbor --repo "path/to/your-app" doctor
+task-harbor --repo "path/to/your-app" manage
+```
+
+`doctor` makes a model call. `manage` uses model calls throughout the run and
+prints a run ID. Save that ID to check progress or resume later.
+
+## CLI commands
+
+Before spending model usage, run `task-harbor check`. It checks Git, the backlog,
+configuration, agent executable availability, required environment, and whether
+verification and call limits are configured. It reads local files without
+creating configuration, running project commands, or testing provider
+authentication. Errors return exit code 2; warnings explain missing safeguards.
+Use `check --json` for structured results.
+
+Find saved run IDs with `task-harbor runs`, or filter with
+`task-harbor runs --status paused`. `runs --json` includes task counts, blocked
+counts, stop reasons, and integration branches. Unreadable runs are reported
+without hiding healthy ones. These are persisted snapshots: “unfinished” does
+not mean a process is currently running.
+
+All commands accept `--repo` before the command. Replace `RUN_ID` below with the
+ID printed by `manage`.
+
+| Command | What it does |
+| --- | --- |
+| `guide` | Setup, usage, and troubleshooting help |
+| `tui` (or no command) | Open the dashboard |
+| `--version` | Show installed version |
+| `init` | Create the configuration and sample backlog |
+| `validate` | Check backlog format and dependencies without calling a model |
+| `check [--json]` | Audit local readiness without executing project commands or calling models |
+| `runs [--status paused] [--json]` | Find saved runs; status filters also accept `unfinished` and `complete` |
+| `doctor` | Validate the backlog and make a test call to the selected agent |
+| `manage` | Start a new run |
+| `status --run-id RUN_ID` | Show saved task status and usage |
+| `report --run-id RUN_ID` | Print a JSON report |
+| `report --run-id RUN_ID --html report.html` | Save an HTML report |
+| `stop --run-id RUN_ID` | Request a pause after in-flight calls finish |
+| `resume --run-id RUN_ID` | Continue a saved run |
+| `retry --run-id RUN_ID --task BUG-001` | Allow a blocked task to try again; then use `resume` |
+| `cleanup --run-id RUN_ID` | Remove run worktrees, keeping branches and logs |
+
+Status, reports, stop, retry, and cleanup do not call a model. Reports are
+snapshots; generate a new one to see updates. Retry and resume keep existing
+usage counts.
+
+## What happens during a run
+
+Task Harbor plans up to four tasks at once, but implements them one at a time.
+Each implementation gets a local checkpoint commit. Configured checks run first,
+then a separate agent checks the acceptance criteria. Passing work is merged into
+the integration branch, with code review every three passes by default.
+
+A failed task gets two repair attempts in the same session. Further failures
+trigger diagnosis and a fresh session, up to a configured limit.
+
+Run state, plans, checks, and logs are saved under `.manager/runs/<run-id>/`.
+Worktrees are stored beside your repository. Edit task requirements before
+starting a new run; `resume` uses saved requirements, not later backlog edits.
+
+Agents execute local commands. The permission settings and worktrees are not a
+substitute for an isolated machine when working with untrusted code. After a hard
+crash, stop any remaining agent processes before resuming.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Tests use simulated agent responses and real temporary Git repositories. CI runs
+on Windows and Linux with Python 3.11 and 3.14. These tests do not establish live model quality or account compatibility; see
+[EVALUATION.md](EVALUATION.md) for opt-in live evaluations.
+
+- [Configuration and provider details](docs/CONFIGURATION.md)
+- [Architecture](ARCHITECTURE.md)
+- [Workflow](WORKFLOW.md)
+- [Evaluation](EVALUATION.md)
+- [Changelog](CHANGELOG.md)
+- [Technical status report](TECHNICAL_STATUS.md)
+
+## Website
+
+The landing page lives in [website/](website/README.md). It uses static HTML, CSS,
+and JavaScript, with an interactive example workflow and installation guide.
+
+## License
+
+Task Harbor is available under the [MIT License](LICENSE).

task_harbor-0.7.0/README.md

@@ -0,0 +1,276 @@
+# Task Harbor
+
+Task Harbor is a command-line tool that runs coding tasks with Claude Code or
+Codex. It reads a Markdown backlog, plans each task, makes changes in separate
+Git worktrees, and checks the results before merging them into a local branch.
+
+It does not push changes or merge them into your original branch. You review the
+result on `manager/integration/<run-id>`.
+
+## Check the work before accepting it
+
+Configure tests once, then inspect the exact commands, checkpoint, and full diff
+for each task. Task agreements capture scope and unanswered questions. A failed
+check stops approval; a missing environment pauses work before more model calls.
+
+- [Set up checks and task agreements](docs/VERIFICATION.md)
+- [Compare Harbor with a direct agent](EVALUATION.md)
+
+```sh
+task-harbor preflight
+task-harbor review --run-id RUN_ID --html review.html
+```
+
+In the dashboard, press **E** for task evidence or **P** for suggested checks.
+
+## Install
+
+You need Python 3.11+, Git, and either Claude Code or Codex installed and signed in.
+The repository you want to work on must have at least one commit and a configured
+Git author.
+
+Install the Python package directly from this repository (no clone required):
+
+```sh
+python -m pip install "git+https://github.com/rhit-nayeems/task-harbor.git"
+task-harbor --version
+task-harbor guide
+```
+
+The dashboard is included. This project is not published to PyPI yet; do not use
+`pip install task-harbor` expecting this repository's package.
+
+<details>
+<summary>Isolated install, upgrades, and command-not-found fixes</summary>
+
+With pipx installed, use an isolated application environment:
+
+```sh
+pipx install "git+https://github.com/rhit-nayeems/task-harbor.git"
+pipx ensurepath
+```
+
+Restart your terminal after changing PATH. For a regular pip installation,
+`python -m task_harbor` works with the same arguments if the executable is not
+on PATH. Use the same Python interpreter you installed with.
+
+Upgrade a pip installation:
+
+```sh
+python -m pip install --upgrade "git+https://github.com/rhit-nayeems/task-harbor.git"
+```
+
+For pipx, use `pipx upgrade task-harbor`. Uninstall with `python -m pip uninstall
+task-harbor` or `pipx uninstall task-harbor`, respectively.
+
+</details>
+
+[First run](#start-a-run) · [Commands](#cli-commands) · [Configuration](docs/CONFIGURATION.md)
+
+## Terminal dashboard
+
+![Task dashboard with sample data](docs/terminal-dashboard.svg)
+
+<details>
+<summary>See first-run setup and built-in help</summary>
+
+![First-run screen](docs/terminal-welcome.svg)
+![Built-in help screen](docs/terminal-help.svg)
+![Task evidence screen with sample data](docs/terminal-evidence.svg)
+
+</details>
+
+These are captures of the actual terminal interface. The task dashboard uses
+sample run data. Open it inside your project:
+
+```sh
+task-harbor
+```
+
+Running `task-harbor` (or `python -m task_harbor`) without a command opens the
+dashboard for the current directory. `--help` lists the other commands.
+
+The dashboard shows saved runs, task status, dependencies, recent events, agent
+calls, and reported costs. Select a run with the picker and use the arrow keys
+to inspect tasks. Tab changes panes, F1 opens help, `r` refreshes, and `q` exits. It also
+refreshes automatically every two seconds.
+
+A run is one execution of your backlog. The run picker appears only after a run
+exists in the selected project.
+
+Use **Set up** to create the configuration and sample backlog, edit those files,
+then click **Validate**. **New run** and **Resume** show the provider, model, and
+call limit before you confirm agent work. **Stop** requests a pause after current
+calls finish. Closing the dashboard does not stop a launched run.
+
+Viewing progress does not consume tokens. Starting or resuming work does.
+Launch output is saved in `.manager/launch-logs/` (or your configured manager
+directory). Launch errors appear above the task list. Unreported costs are unknown.
+Use `tui --run-id <id>` to open a specific saved run. All commands below still work
+without the dashboard.
+
+## Start a run
+
+Replace `path/to/your-app` with the repository you want Task Harbor to work on.
+Use `--repo` before the command.
+
+```sh
+task-harbor --repo "path/to/your-app" init
+```
+
+This creates `.manager/config.json` and a sample `BACKLOG.md` in that repository.
+An existing backlog is kept. Replace the sample task with your own work:
+
+```markdown
+## BUG-001 — Fix empty search results
+- **Priority:** critical_bug
+- **Status:** UNPLANNED
+- **Dependencies:** —
+- **Acceptance criteria:**
+  - An empty search shows a message instead of crashing
+  - Existing search tests pass
+- **Next action:** Plan the task
+```
+
+Use a different ID for each task. List dependency IDs separated by commas.
+See [BACKLOG.example.md](BACKLOG.example.md) for a longer example.
+
+### Choose Claude or GPT
+
+Edit `.manager/config.json` before starting. Claude is the default:
+
+```json
+{
+  "provider": "claude",
+  "model": "opus",
+  "effort": "medium"
+}
+```
+
+For GPT, sign in with `codex login` and change these fields:
+
+```json
+{
+  "provider": "codex",
+  "model": "gpt-6.1-sol",
+  "effort": "medium",
+  "max_run_cost_usd": null,
+  "max_call_cost_usd": null
+}
+```
+
+Use a model available to your account. Provider choice applies to the whole run;
+you cannot switch providers when resuming it.
+
+### Set checks and limits
+
+Add your project's test or build commands to the configuration. For example:
+
+```json
+{
+  "verification_commands": ["python -m pytest"],
+  "max_agent_calls": 100,
+  "max_task_agent_calls": 20
+}
+```
+
+These call limits are examples; the defaults are unlimited. Both providers support
+call limits and timeouts. Only Claude supports estimated dollar caps. Codex
+requires both dollar-budget settings to be `null`.
+
+Now validate the backlog, check the selected agent, and start:
+
+```sh
+task-harbor --repo "path/to/your-app" validate
+task-harbor --repo "path/to/your-app" doctor
+task-harbor --repo "path/to/your-app" manage
+```
+
+`doctor` makes a model call. `manage` uses model calls throughout the run and
+prints a run ID. Save that ID to check progress or resume later.
+
+## CLI commands
+
+Before spending model usage, run `task-harbor check`. It checks Git, the backlog,
+configuration, agent executable availability, required environment, and whether
+verification and call limits are configured. It reads local files without
+creating configuration, running project commands, or testing provider
+authentication. Errors return exit code 2; warnings explain missing safeguards.
+Use `check --json` for structured results.
+
+Find saved run IDs with `task-harbor runs`, or filter with
+`task-harbor runs --status paused`. `runs --json` includes task counts, blocked
+counts, stop reasons, and integration branches. Unreadable runs are reported
+without hiding healthy ones. These are persisted snapshots: “unfinished” does
+not mean a process is currently running.
+
+All commands accept `--repo` before the command. Replace `RUN_ID` below with the
+ID printed by `manage`.
+
+| Command | What it does |
+| --- | --- |
+| `guide` | Setup, usage, and troubleshooting help |
+| `tui` (or no command) | Open the dashboard |
+| `--version` | Show installed version |
+| `init` | Create the configuration and sample backlog |
+| `validate` | Check backlog format and dependencies without calling a model |
+| `check [--json]` | Audit local readiness without executing project commands or calling models |
+| `runs [--status paused] [--json]` | Find saved runs; status filters also accept `unfinished` and `complete` |
+| `doctor` | Validate the backlog and make a test call to the selected agent |
+| `manage` | Start a new run |
+| `status --run-id RUN_ID` | Show saved task status and usage |
+| `report --run-id RUN_ID` | Print a JSON report |
+| `report --run-id RUN_ID --html report.html` | Save an HTML report |
+| `stop --run-id RUN_ID` | Request a pause after in-flight calls finish |
+| `resume --run-id RUN_ID` | Continue a saved run |
+| `retry --run-id RUN_ID --task BUG-001` | Allow a blocked task to try again; then use `resume` |
+| `cleanup --run-id RUN_ID` | Remove run worktrees, keeping branches and logs |
+
+Status, reports, stop, retry, and cleanup do not call a model. Reports are
+snapshots; generate a new one to see updates. Retry and resume keep existing
+usage counts.
+
+## What happens during a run
+
+Task Harbor plans up to four tasks at once, but implements them one at a time.
+Each implementation gets a local checkpoint commit. Configured checks run first,
+then a separate agent checks the acceptance criteria. Passing work is merged into
+the integration branch, with code review every three passes by default.
+
+A failed task gets two repair attempts in the same session. Further failures
+trigger diagnosis and a fresh session, up to a configured limit.
+
+Run state, plans, checks, and logs are saved under `.manager/runs/<run-id>/`.
+Worktrees are stored beside your repository. Edit task requirements before
+starting a new run; `resume` uses saved requirements, not later backlog edits.
+
+Agents execute local commands. The permission settings and worktrees are not a
+substitute for an isolated machine when working with untrusted code. After a hard
+crash, stop any remaining agent processes before resuming.
+
+## Development
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Tests use simulated agent responses and real temporary Git repositories. CI runs
+on Windows and Linux with Python 3.11 and 3.14. These tests do not establish live model quality or account compatibility; see
+[EVALUATION.md](EVALUATION.md) for opt-in live evaluations.
+
+- [Configuration and provider details](docs/CONFIGURATION.md)
+- [Architecture](ARCHITECTURE.md)
+- [Workflow](WORKFLOW.md)
+- [Evaluation](EVALUATION.md)
+- [Changelog](CHANGELOG.md)
+- [Technical status report](TECHNICAL_STATUS.md)
+
+## Website
+
+The landing page lives in [website/](website/README.md). It uses static HTML, CSS,
+and JavaScript, with an interactive example workflow and installation guide.
+
+## License
+
+Task Harbor is available under the [MIT License](LICENSE).

task_harbor-0.7.0/opus_manager/__init__.py

@@ -0,0 +1,3 @@
+"""Task Harbor: local Claude and GPT engineering supervisor."""
+
+__version__ = "0.4.0"

task_harbor-0.7.0/opus_manager/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

task_harbor-0.7.0/opus_manager/agent.py

@@ -0,0 +1,17 @@
+"""Provider-neutral result and error types."""
+from dataclasses import dataclass
+from typing import Any
+
+
+class AgentError(RuntimeError):
+    def __init__(self, message: str, raw: dict | None = None):
+        super().__init__(message)
+        self.raw = raw
+
+
+@dataclass
+class AgentResult:
+    text: str
+    session_id: str | None
+    raw: dict[str, Any]
+    returncode: int