task-agent 1.3.10__tar.gz → 1.3.12__tar.gz

{task_agent-1.3.10 → task_agent-1.3.12}/.gitignore

@@ -20,3 +20,5 @@ docks/tasks
 
 # task-agent: human-facing store symlink
 docs/tasks
+.map/
+.ma/prompt/

{task_agent-1.3.10 → task_agent-1.3.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: task-agent
-Version: 1.3.10
+Version: 1.3.12
 Summary: A prioritized, file-based task queue for autonomous agentic workers
 Project-URL: Homepage, https://github.com/InTEGr8or/task-agent
 Project-URL: Repository, https://github.com/InTEGr8or/task-agent.git

{task_agent-1.3.10 → task_agent-1.3.12}/docs/README.md

@@ -14,6 +14,8 @@ Welcome to the comprehensive documentation for **Task Agent**, a prioritized, fi
   - Information on project setup, testing, and release processes.
 - [**Station Map**](./STATION-MAP.md)
   - Formal declaration of task-agent as a typed file-path station system: stations, transitions, edge roles, and conformance gaps.
+- [**ADR 0001: store sync**](./adr/0001-sync-task-stores-with-an-operation-log.md)
+  - Git carries an append-only per-writer operation log. The station tree is a projection.
 
 ## 🚀 Quick Start
 

task_agent-1.3.12/docs/adr/0001-sync-task-stores-with-an-operation-log.md

@@ -0,0 +1,121 @@
+# ADR 0001: Sync task stores with an append-only operation log
+
+- Status: Accepted
+- Date: 2026-10-29
+- Scope: task-agent station stores, their `*-tasks` git remotes, native Windows clients, and handterm `ta`
+
+## Context
+
+A task store is a typed path queue. Stations (`pending/`, `draft/`, `active/`, `completed/`, `deleted/`) hold one directory per slug. `mission.usv` is the priority index. Leases live in `lease.json`. The inbox is same-machine only.
+
+Each durable store is already its own git repo under the machine data root (`TA_DATA_ROOT`, else `$XDG_DATA_HOME/task-agent`, else `~/.local/share/task-agent`). The subject repo stays separate. GitHub sibling repos are the remotes, for example `InTEGr8or/task-agent-tasks` and `bizkite-co/handterm-tasks`. `ta store remote {suggest,create,set,attach}` configures that remote. Mutations commit locally through `_commit_task_store`. They do not push. There is no `ta store pull` and no `ta store clone`.
+
+That layout is the right archive. It is a weak multi-writer database.
+
+- WSL and native Windows use different home directories. `ta store migrate` is refused on native Windows because of that split and because git often materializes symlinks as text files. A PowerShell client cannot replay the WSL migration.
+- Two clones of one store on one PC diverge even when a remote exists. This machine's `task-agent-tasks` history had already moved past the GitHub `main` tip.
+- The hot files are `mission.usv` and directory renames. Overlapping edits do not merge. `git pull --rebase` before every push stops the worker on the first conflict.
+- handterm `ta` already targets `bizkite-co/handterm-tasks` through the GitHub Contents API. It writes a single markdown file, does not update `mission.usv`, and leaves the pending copy in place when it marks a task active. A phone cannot join a rebase.
+
+Workers that must keep working are: WSL `ta`, a Windows client of the same PC, other machines, and handterm on a device that only has HTTPS.
+
+## Decision
+
+Git remains the transport and the history log. The replicated object is an append-only operation log. The station tree and `mission.usv` are a projection of that log.
+
+### Log shape
+
+Ops live inside the store:
+
+```text
+.task-agent/ops/<writer-id>/<op-id>.op.json
+```
+
+`<writer-id>` is one id per machine, stored at `<data-root>/writer-id` (override with `TA_WRITER_ID`). A writer appends only under its own directory. Sync unions every writer's files. Apply order is `(at, id)` with UTC timestamps. A hybrid logical clock can replace that sort later without moving the files.
+
+Each file is one JSON object:
+
+| Field | Meaning |
+| :--- | :--- |
+| `v` | Schema version. `1` for this ADR. |
+| `id` | Unique, time-prefixed id. |
+| `writer` | Machine writer id. |
+| `at` | UTC timestamp. |
+| `verb` | `create`, `move`, `edges`, `rename`, `lease`, `release`. |
+| `slug` | Task slug the verb applies to. |
+| `payload` | Verb fields. `create` carries `name` and `station`. `move` carries `station` and `from_station`. `edges` carries `blocked_by` and `subtask_of`. `rename` carries `new_slug`. |
+
+Rules for version 1:
+
+- The first `create` for a slug wins. A second `create` for the same slug is a no-op.
+- A later `move` for the same slug wins.
+- `edges` replaces the fields it names.
+- Task markdown still rides in the same commit as the op while `ta` is the writer. A client with no working tree (handterm) puts the new task body in the `create` payload so a materializer can write the file.
+- `ingest` is not an op. Adoption of loose markdown stays a local repair, not a sync verb.
+
+### Same machine
+
+The data root stays on the WSL Linux filesystem (`~/.local/share/task-agent`). Do not point `TA_DATA_ROOT` at `/mnt/c` or `%LOCALAPPDATA%`. That creates a second store on NTFS and splits the registry.
+
+Windows PowerShell sets one variable, from `ta store data-root --windows`:
+
+```text
+TA_DATA_ROOT=\\wsl$\Debian\home\<user>\.local\share\task-agent
+```
+
+That UNC is the same directory, not a copy. Code repos may stay on `C:\`. `ta store migrate` run from WSL moves an in-repo `.task-agent/tasks` tree into the Linux data root and records both `/mnt/c/...` and `C:\...` as host paths. There is no gate that blocks `ta` until every repo is migrated. Migrate the checkout you are using. Windows does not run `ta store migrate`.
+
+### Other machines and the phone
+
+`ta sync` (not built yet) pulls the `*-tasks` repo, unions the log, rebuilds `mission.usv` and station moves from the projection, and pushes. Ordinary mutations keep appending ops and committing the projection so current agents still read directories.
+
+handterm `ta`, defaulting to the subject repo's sibling `*-tasks` repo (`handterm` unless `--repo` is set), appends one op with the Git Data API. The branch update compare-and-swaps the expected SHA and retries once. It does not edit `mission.usv` itself.
+
+A sequencer HTTP service may later assign order and fan the same log out. The file format does not change if that service appears. GitHub stays a valid relay until then.
+
+## Consequences
+
+- Concurrent creates of different slugs merge by taking both files.
+- Two moves of one slug have a defined winner (later op id) instead of a rebase conflict in `mission.usv`.
+- The projection can be rebuilt from the log. Until `ta sync` exists, the committed tree is still what `ta next` reads, and the log is written beside it.
+- Clock skew can reorder ops across machines. Acceptable for v1 because ids are the only cross-writer order. A logical clock is a follow-on, not a new store.
+- Writers must not edit another writer's op directory. Git should not present those files as modify/modify conflicts.
+- Existing stores gain ops on the next mutation. Old history is not backfilled.
+
+## Rejected strategies
+
+### Push the materialized tree after every change
+
+Commits already happen. Adding `git push` after `_commit_task_store`, with or without `git pull --rebase`, publishes the projection. The second writer to touch `mission.usv` or rename the same slug loses or stops. handterm's one-file Contents API cannot rebase. Useful only as a one-time backup of a store that has no log yet.
+
+### Two clones on one PC, synced only through GitHub
+
+This is the failure already seen when a centralized store and an ejected copy both stayed writable. Shared `TA_DATA_ROOT` removes the need to sync that pair.
+
+### GitHub Issues as the queue
+
+`ta github sync` is a separate, unfinished, one-way import. Issues have no station paths, no `mission.usv` order, and no leases. Mirroring there would be a third queue.
+
+### GitHub Wiki, Keet, or Matrix as the store
+
+The wiki was rejected as a product path when sibling `*-tasks` repos were chosen. Keet and Matrix rooms configured on a store are notification channels. They are not a file log and not a branch with compare-and-swap.
+
+### CRDT database or hosted SQL sync instead of the file checkout
+
+Automerge, Yjs, ElectricSQL, Turso, and similar systems solve multi-writer sync by replacing the working copy. Agents and `ta` read station directories. The station map is a typed path queue. Putting a list CRDT under the op log is possible later for reorder. Replacing the tree with a hosted database drops the checkout those workers use.
+
+### A bespoke sequencer as the only writer, now
+
+One online API that sequences every transition is a good relay once the phone and several agents are always connected. Offline `ta` would become a client of that service. The op log gets the same ordering rules and still moves through git. The sequencer can be added in front of the log. It is not a reason to pick a different replicated object.
+
+## Implementation status
+
+Accepted and in progress on the task "Sync task stores with an append-only operation log".
+
+| Slice | State |
+| :--- | :--- |
+| This ADR | Accepted |
+| Append ops from store mutations, plus an in-memory reduce | In `src/taskagent/oplog.py` |
+| `ta store sync` | Fast-forward or merge, then replay ops onto the tree and push. A successful store commit runs this when the store has `origin` and that git root is the store itself. A store inside a subject checkout is committed locally and not pushed. `TA_NO_AUTO_SYNC=1` skips the sync. A fetch, merge, or push failure keeps the local commit and aborts a half-finished merge. |
+| handterm `ta new` | One `create` op plus the task file, via `commit-repo-files` (Git Data API, fast-forward ref update, one retry). The Lambda route has to be deployed before a phone can call it. |
+| One-time publish | `ta store sync` pushes when the local store is a fast-forward of GitHub. |

{task_agent-1.3.10 → task_agent-1.3.12}/docs/architecture/README.md

@@ -2,6 +2,8 @@
 
 Task Agent is designed with a "filesystem-as-a-database" philosophy. This ensures that the task queue is highly portable, version-controlled by git, and easily readable by both humans and machines.
 
+Multi-writer sync of a store is an append-only operation log under `.task-agent/ops/<writer-id>/`. Git transports that log. `mission.usv` and the station directories are a projection. See [ADR 0001](../adr/0001-sync-task-stores-with-an-operation-log.md).
+
 ## 📂 Data Storage
 
 All task data is stored within the `docs/tasks/` directory.

{task_agent-1.3.10 → task_agent-1.3.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "task-agent"
-version = "1.3.10"
+version = "1.3.12"
 description = "A prioritized, file-based task queue for autonomous agentic workers"
 readme = "README.md"
 requires-python = ">=3.12"

task_agent-1.3.12/scripts/check_task_worktree_cleanup.py

@@ -0,0 +1,240 @@
+"""Classify task-agent worktrees whose branch is merged and whose task is closed.
+
+A worktree is safe to remove when three local signals all agree:
+
+1. Branch merged: ``issue/<slug>`` is an ancestor of the integration branch
+   (--base, default uat). ``git cherry`` additionally detects content that
+   landed via cherry-pick/rebase (patch-merged); those branches need ``-D``
+   because ``git branch -d`` only trusts ancestry.
+2. Task closed: the task-agent store encodes status as directory location, so
+   the slug under ``completed/YYYY/MM/`` (or ``deleted/``) means closed, while
+   ``active/``, ``pending/``, ``draft/`` mean the worktree may still be a
+   runner staging area.
+3. Nothing to lose: ``git status --porcelain`` in the worktree is empty. A
+   worktree whose directory is gone (prunable registration) counts as clean;
+   removal uses ``git worktree prune`` for those.
+
+Run from any project repo registered in the task-agent registry.
+
+Usage:
+    python scripts/check_task_worktree_cleanup.py            # report only
+    python scripts/check_task_worktree_cleanup.py --remove   # remove safe ones
+    python scripts/check_task_worktree_cleanup.py --remove --allow-patch-merged
+
+--base defaults to the current branch of the repo it runs in.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+REGISTRY_PATH = Path.home() / ".local/share/task-agent/registry.json"
+OPEN_STATUSES = ("active", "pending", "draft")
+CLOSED_STATUSES = ("completed", "deleted")
+
+
+def run_git(
+    args: list[str], cwd: Optional[Path] = None
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args], capture_output=True, text=True, cwd=cwd, check=False
+    )
+
+
+def moniker_from_remote(url: str) -> Optional[str]:
+    tail = url.removesuffix(".git")
+    tail = tail.rsplit(":", 1)[-1] if ":" in tail else tail
+    parts = [p for p in tail.split("/") if p]
+    if len(parts) >= 2:
+        return f"{parts[-2]}/{parts[-1]}"
+    return None
+
+
+def resolve_store(repo: Path, override: Optional[str]) -> Optional[Path]:
+    if override:
+        return Path(override).expanduser()
+    if not REGISTRY_PATH.is_file():
+        return None
+    try:
+        registry = json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    entries = registry.get("stores", {})
+    for entry in entries.values():
+        if str(repo) in entry.get("host_paths", []):
+            return Path(entry["store_path"])
+    remote = run_git(["remote", "get-url", "origin"], cwd=repo).stdout.strip()
+    moniker = moniker_from_remote(remote)
+    if moniker and moniker in entries:
+        return Path(entries[moniker]["store_path"])
+    return None
+
+
+def task_status(store: Path, slug: str) -> str:
+    for status in OPEN_STATUSES:
+        if (store / status / slug).is_dir():
+            return status
+    if (store / "deleted" / slug).is_dir():
+        return "deleted"
+    for match in (store / "completed").glob(f"*/*/{slug}"):
+        if match.is_dir():
+            return "completed"
+    return "not-found"
+
+
+def merged_state(repo: Path, branch: str, base: str) -> str:
+    if run_git(["merge-base", "--is-ancestor", branch, base], cwd=repo).returncode == 0:
+        return "ancestor"
+    cherry = run_git(["cherry", base, branch], cwd=repo)
+    if cherry.returncode == 0:
+        lines = [line for line in cherry.stdout.splitlines() if line.strip()]
+        if lines and all(line.startswith("-") for line in lines):
+            return "patch"
+    return "no"
+
+
+def dirty_count(worktree: Path) -> Optional[int]:
+    if not worktree.is_dir():
+        return None
+    proc = run_git(["status", "--porcelain"], cwd=worktree)
+    return len([line for line in proc.stdout.splitlines() if line.strip()])
+
+
+def issue_worktrees(repo: Path) -> list[tuple[Path, str]]:
+    proc = run_git(["worktree", "list", "--porcelain"], cwd=repo)
+    pairs: list[tuple[Path, str]] = []
+    worktree: Optional[Path] = None
+    for line in proc.stdout.splitlines():
+        if line.startswith("worktree "):
+            worktree = Path(line.split(" ", 1)[1])
+        elif line.startswith("branch refs/heads/issue/"):
+            branch = line.split(" ", 1)[1][len("refs/heads/") :]
+            if worktree is not None:
+                pairs.append((worktree, branch))
+    return pairs
+
+
+@dataclass
+class Row:
+    slug: str
+    worktree: Path
+    branch: str
+    merged: str
+    status: str
+    dirty: Optional[int]
+    verdict: str
+
+
+def classify(repo: Path, store: Optional[Path], base: str) -> list[Row]:
+    rows: list[Row] = []
+    for worktree, branch in issue_worktrees(repo):
+        slug = branch[len("issue/") :]
+        merged = merged_state(repo, branch, base)
+        status = task_status(store, slug) if store else "unknown-store"
+        dirty = dirty_count(worktree)
+        if status not in CLOSED_STATUSES:
+            verdict = f"KEEP (task {status})"
+        elif merged == "no":
+            verdict = "REVIEW (unmerged)"
+        elif dirty:
+            verdict = "REVIEW (dirty)"
+        elif merged == "patch":
+            verdict = "REMOVE (patch-merged, -D)"
+        else:
+            verdict = "REMOVE"
+        rows.append(Row(slug, worktree, branch, merged, status, dirty, verdict))
+    return rows
+
+
+def remove_row(repo: Path, row: Row, force_branch: bool) -> bool:
+    if row.worktree.is_dir():
+        proc = run_git(["worktree", "remove", str(row.worktree)], cwd=repo)
+    else:
+        proc = run_git(["worktree", "prune"], cwd=repo)
+    if proc.returncode != 0:
+        print(f"  worktree remove FAILED: {row.worktree}")
+        return False
+    delete_flag = "-D" if force_branch else "-d"
+    proc = run_git(["branch", delete_flag, row.branch], cwd=repo)
+    if proc.returncode != 0:
+        print(f"  branch {delete_flag} FAILED: {row.branch}: {proc.stderr.strip()}")
+        return False
+    print(f"  removed {row.branch} ({row.worktree.name})")
+    return True
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--base", help="integration branch (default: current branch)")
+    parser.add_argument("--store", help="task-agent store path override")
+    parser.add_argument(
+        "--remove",
+        action="store_true",
+        help="remove worktrees/branches verdicted REMOVE",
+    )
+    parser.add_argument(
+        "--allow-patch-merged",
+        action="store_true",
+        help="also remove patch-merged branches (deleted with -D)",
+    )
+    args = parser.parse_args(argv)
+
+    toplevel = run_git(["rev-parse", "--show-toplevel"]).stdout.strip()
+    if not toplevel:
+        print("not a git repository")
+        return 1
+    repo = Path(toplevel)
+    store = resolve_store(repo, args.store)
+    base = (
+        args.base
+        or run_git(["rev-parse", "--abbrev-ref", "HEAD"], cwd=repo).stdout.strip()
+    )
+    if not base:
+        print("could not determine integration branch; pass --base")
+        return 1
+    if store is None:
+        print("warning: task-agent store not found; task status unavailable")
+    else:
+        print(f"store: {store}")
+
+    rows = sorted(classify(repo, store, base), key=lambda r: (r.verdict, r.slug))
+    for row in rows:
+        if row.dirty is None:
+            dirty = "missing"
+        elif row.dirty:
+            dirty = f"{row.dirty} changed"
+        else:
+            dirty = "clean"
+        print(
+            f"{row.verdict:<26} merged={row.merged:<8} "
+            f"task={row.status:<10} {dirty:<12} {row.branch}"
+        )
+
+    removable = [r for r in rows if r.verdict == "REMOVE"]
+    patchable = [r for r in rows if r.verdict == "REMOVE (patch-merged, -D)"]
+    print(
+        f"\n{len(removable)} removable, {len(patchable)} patch-merged, "
+        f"{len(rows) - len(removable) - len(patchable)} to keep/review"
+    )
+    if patchable and not args.allow_patch_merged:
+        print("patch-merged branches need --allow-patch-merged (or manual -D)")
+
+    if args.remove:
+        ok = True
+        for row in removable:
+            ok = remove_row(repo, row, force_branch=False) and ok
+        if args.allow_patch_merged:
+            for row in patchable:
+                ok = remove_row(repo, row, force_branch=True) and ok
+        return 0 if ok else 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())