Metadata-Version: 2.4
Name: hypergumbo-tracker
Version: 0.5.0
Summary: YAML-backed structured tracker for agent governance
Author: Hypergumbo contributors
License: MPL-2.0
License-File: LICENSE
Keywords: agent-governance,cli,tracker,yaml
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Requires-Dist: bcrypt>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: proquint~=0.2.1
Requires-Dist: pygments~=2.20.0
Requires-Dist: pyyaml~=6.0.3
Requires-Dist: requests~=2.33.0
Requires-Dist: rich~=14.3.2
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: starlette>=1.0
Requires-Dist: textual~=7.5
Requires-Dist: uvicorn>=0.30
Requires-Dist: watchfiles>=1.0
Requires-Dist: webauthn>=2.0
Provides-Extra: dedup
Requires-Dist: onnxruntime~=1.17; extra == 'dedup'
Requires-Dist: tokenizers~=0.21; extra == 'dedup'
Provides-Extra: dev
Requires-Dist: hypothesis~=6.100; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest-cov~=7.0.0; extra == 'dev'
Requires-Dist: pytest-textual-snapshot~=1.1; extra == 'dev'
Requires-Dist: pytest-xdist~=3.8.0; extra == 'dev'
Requires-Dist: pytest<10,>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: MPL-2.0 -->
# hypergumbo-tracker

Structured work tracker for AI agent governance. Append-only YAML op-logs
that are git-merge-safe, causally ordered, and support field-level access
control. Agents get structured task selection; humans get locks, tier control,
a TUI, and a web interface.

See [CHANGELOG.md](CHANGELOG.md) for release history.

## Setup

### 1. Install

Install the tracker into your project's virtual environment:

```bash
# As either user (whoever owns the venv)
source .venv/bin/activate   # or wherever your venv lives
pip install hypergumbo-tracker
```

### 2. Create an agent user

The tracker uses `os.getuid()` to distinguish agents from humans. Run the
agent as a separate OS user for OS-enforced access control:

```bash
# As the human user (needs sudo)
sudo useradd -m myproject_agent
sudo groupadd project-dev
sudo usermod -aG project-dev yourname
sudo usermod -aG project-dev myproject_agent
```

**Important:** Group membership doesn't take effect in existing shells. Either
log out and back in, or run `newgrp project-dev` in your current session.

If the repo lives under the agent's home directory, the human user also needs
traversal access:

```bash
# As the human user (needs sudo)
sudo chmod o+rx /home/myproject_agent
```

### 3. Run the wizard

```bash
# As the human user (recommended — can auto-fix config ownership)
cd /path/to/your-repo   # must be the repo root
htrac setup
```

This creates directories, configures git plumbing (merge=union, textconv),
copies the config template, sets file permissions, and reports anything that
needs attention. It's idempotent — run it again anytime to diagnose issues.

The wizard handles common pitfalls automatically:
- **Running as agent?** Prompts to switch to the human user and prints
  ready-to-paste setup commands (venv activation, `htrac setup`, group fixes).
- **Cross-user repo ownership?** Auto-adds `safe.directory` to git config.
- **`.git/config` not writable?** Falls back to `--global` for textconv.
- **Two-user group misconfigured?** Reports specific problems (missing
  group-write, missing setgid, user not in group) with fix commands that
  include the detected group name.
- **Config owned by wrong user?** Auto-fixes when run as human.

Set group ownership on the directories the wizard created so both users can
write to ops files:

```bash
# As the human user (needs sudo)
sudo chgrp -R project-dev .agent/tracker .agent/tracker-workspace
sudo chmod -R g+rws .agent/tracker/.ops .agent/tracker-workspace .agent/tracker-workspace/.ops .agent/tracker-workspace/stealth
```

Verify the human user can write:

```bash
# As the human user (must have run newgrp project-dev or started a new session)
touch .agent/tracker-workspace/.ops/test && rm .agent/tracker-workspace/.ops/test
```

If you get "Permission denied", check that `newgrp project-dev` was run (or
start a new login session).

**Note:** Git does not track file ownership or group permissions. After a fresh
`git clone`, you must re-run `htrac setup` and repeat the `chgrp`/`chmod`
commands above.

You now have:

- **`htrac`** — CLI for agents (`htrac ready`, `htrac add`, `htrac update`, ...)
- **`htrac tui`** — interactive terminal UI for humans
- **`htrac setup`** — re-runnable setup wizard

## Permission testing

For two-user setups, verify the permission boundary end-to-end with the
[Permission Test Playbook](tests/permission/README.md). The playbook
exercises human-only operations (lock, stealth, delete), agent restrictions,
and filesystem permission checks. If tests fail, re-run `htrac setup` (see
[Run the wizard](#3-run-the-wizard) above) and follow its fix instructions.

## Agent usage

These commands are run **as the agent user** (e.g. `myproject_agent`). The
tracker records `by: agent` on each operation, and human-only commands
(`lock`, `stealth`, `discuss --clear`) are blocked.

```bash
htrac ready                    # What should I work on?
htrac check-messages           # Any unread human messages?
htrac update :1 --status in_progress   # Claim the top item
htrac add --kind work_item --title "Add Dart analyzer" --priority 1
htrac update INV-lusab --status done --note "Fixed in PR #42"
htrac show INV-lusab           # Full item details
htrac list --status todo_hard  # Filtered listing
htrac discuss INV-lusab "Root cause confirmed in parser.py"
htrac deps INV-lusab           # Dependency graph view
htrac batch < commands.txt     # Bulk operations
```

**Positional aliases:** `htrac ready` and `htrac list` assign shortcuts `:1`,
`:2`, etc. to their output rows. Use them in the next command (e.g.
`htrac update :1 --status in_progress`). Aliases reset after any non-list
command.

**`--note`** on `update` is shorthand for a follow-up `discuss` entry — e.g.
`htrac update WI-foo --status done --note "Fixed in PR #42"` updates status
and records why in one command.

Use `htrac <command> --help` for all options. Use `--json` on any command for
machine-readable output.

## Human usage

These commands are run **as the human user** (e.g. `yourname`). The tracker
records `by: human` on each operation, enabling human-only commands that
agents cannot access.

```bash
htrac tui                      # Interactive terminal UI
htrac lock INV-lusab status    # Prevent agent from changing status
htrac stealth WI-nipam         # Hide item from git (human-only)
htrac discuss INV-lusab --clear  # Clear discussion (human-only)
```

The TUI supports three layouts (compact/standard/wide) based on terminal size.
Keybindings: `q` quit, `f` filter, `d` discuss, `m` move tier, `n` new item,
`e` edit, `l` lock/unlock, `S` screenshot. Screenshot mode supports annotation
with rectangles (`R` + drag), arrows (`A` + drag), and numbered text labels
(`L` + click).

Both users can read all items — the access control only applies to writes.

## Web interface

`htrac serve` starts a local web server for browser-based access:

```bash
htrac serve                    # Foreground on 127.0.0.1:7380
htrac serve --background       # Daemonize
htrac serve --status           # Check if running
htrac serve --stop             # Shut down
```

The server exposes a REST API (`/api/items`, `/api/ready`, create/update/discuss
endpoints) and a WebSocket (`/ws`) for real-time state sync. A filesystem
watcher detects CLI/TUI ops file changes and auto-broadcasts to all connected
clients.

**Auth:** WebAuthn/FIDO2 hardware key authentication (ES256, RS256) and bcrypt
password verification. Per-credential rate limiting with exponential backoff.
Configure in `config.yaml` under `auth`.

The web frontend (Vite + TypeScript + BlockSuite) lives in
`packages/htrac-frontend/`. It uses a service worker for cache-first loading
and reconnects to WebSocket with exponential backoff.

## Core concepts

**Items** have an ID, kind, status (todo_hard → done), priority (0–4, lower =
higher), and optional fields, tags, and discussion.

**IDs** are content-hash proquints: `INV-lusab-bired`, `WI-nipam-fotil` —
deterministic, collision-resistant, pronounceable.

**Kinds** define item shape. Defaults: `invariant` (INV), `meta_invariant`
(META), `work_item` (WI). Add custom kinds in `config.yaml`.

**Tiers** control visibility:

| Tier | Path | Git-tracked | Purpose |
|------|------|-------------|---------|
| canonical | `.agent/tracker/.ops/` | Yes | Shared with upstream |
| workspace | `.agent/tracker-workspace/.ops/` | Yes | Fork-local |
| stealth | `.agent/tracker-workspace/stealth/` | No | Local-only |

Move items between tiers: `promote`, `demote`, `stealth`, `unstealth`.

**Dependencies:** `X.isbefore = [Y]` means finish X before Y. The `ready`
command respects this.

**Auto-sync:** When pending ops exceed a threshold (default 40 lines), the
tracker automatically commits, pushes, polls CI, and merges — keeping tracker
state synced across branches without manual intervention.

## Stop hook integration

Three commands for autonomous-agent stop hooks:

```bash
# Called by the stop hook (runs as the agent user)
htrac count-todos              # Number of blocking items (0 = ok to stop)
htrac hash-todos               # SHA-256 fingerprint (circuit-breaker detection)
htrac guidance                 # Generate guidance file for the agent
```

Example hook snippet:

```bash
count=$(htrac count-todos 2>/dev/null || echo 0)
if [ "$count" -gt 0 ]; then
  echo "BLOCKED: $count items remain"
  exit 1
fi
```

## Pre-commit integration

```bash
# In .githooks/pre-commit:
staged_ops=$(git diff --cached --name-only -- '*.ops')
if [ -n "$staged_ops" ]; then
  htrac validate $staged_ops --check-locks --strict || exit 1
fi
```

`htrac setup` also configures the git textconv driver so `git diff` shows
compiled item state instead of raw YAML.

## Configuration

Config loading order: `config.yaml` (gitignored, yours to edit) →
`config.yaml.template` (tracked, shared) → built-in defaults.

`htrac setup` copies the template to `config.yaml` if it doesn't exist and
ensures it's owned by the human user (governance settings shouldn't be
agent-writable). See the template file for the full schema. Key sections:

- **`kinds`** — item types with optional `fields_schema`
- **`statuses`** — lifecycle states
- **`stop_hook`** — which statuses block agent stopping, scope (all vs workspace)
- **`actor_resolution.agent_usernames`** — fnmatch patterns (default: `["*_agent"]`)
- **`lamport_branches`** — branches for clock sync and cross-branch locks

## Fork workflow

```bash
# As the agent user (in your fork)
htrac fork-setup               # Sets scope to workspace-only
```

This makes `count-todos` and `hash-todos` ignore upstream canonical items so
they don't block your agent. Items you create default to workspace; the
upstream maintainer can `promote` them after merge.

## License

[Mozilla Public License 2.0](LICENSE). Other hypergumbo packages are
AGPL-3.0-or-later. See the repository root LICENSE and CONTRIBUTING.md.
