pi-orca-tasks

File-backed task DAG with locking, state machine, and interactive UI

Version: 0.0.2-dev
License: MIT

Overview

A complete task management extension for Pi, providing file-backed tasks with a directed acyclic graph (DAG) for dependency tracking, PID-based locking for concurrent safety, a full state machine with 9 transitions, and an interactive TUI overlay.

Features

• State machine — 9 transitions: create, claim, complete, fail, abandon, unclaim, retry, reopen, unlock
• DAG dependencies — cycle detection, cascading blocked status, transitive dependent resolution
• PID-based locking — dead-process detection with automatic unlock
• Notes with resumption — append timestamped notes, resume context on re-claim
• Label filtering — key-value labels with special values (_unset, _empty, _blank)
• Two-mode HUD widget — compact (less) and expanded multi-column (more) views
• Idle polling — checks for external task changes every 30s and refreshes the widget automatically
• Interactive overlay — task browser with list, detail, and filter screens
• Keyboard shortcut — Alt+T toggles HUD visibility

Tool Actions

| Action | Description | Required Params | |--------|-------------|-----------------| | create | Create a new task | title | | claim | Claim a task for work (pending → in_progress) | taskId | | complete | Mark task complete (in_progress → completed) | taskId | | fail | Mark task failed with reason (in_progress → failed) | taskId, note | | abandon | Abandon task with reason (in_progress → abandoned) | taskId, note | | unclaim | Release claim (in_progress → pending) | taskId | | retry | Retry a failed task (failed → pending) | taskId | | reopen | Reopen an abandoned task (abandoned → pending) | taskId | | unlock | Force-release a stuck lock | taskId | | update | Update title, labels, or dependencies | taskId | | note | Append a note to a task | taskId, note | | list | List tasks with optional status/label filter | (optional: status, labels) |

Slash Commands

| Command | Description | |---------|-------------| | /tasks | Open interactive task overlay | | /tasks more | Show expanded multi-column HUD widget | | /tasks less | Show compact 1-line HUD widget | | /tasks list [status] | List tasks, optionally filtered by status | | /tasks create <title> | Quick-create a task | | /tasks stuck | Scan for stuck tasks (dead locks) | | /tasks unlock <id> | Force-release a stuck task lock | | /tasks deps <id> | Show dependency graph for a task | | /tasks validate [id] | Validate task file integrity |

Widget Modes

Compact (/tasks less) — default

Single summary line with status counts for all states:

📋 Tasks 3/7 done | ◉2 in-progress ○1 pending ✗1 failed ⊘1 blocked —1 abandoned   /tasks more

Expanded (/tasks more)

Multi-column task list with responsive layout. Adapts columns based on terminal width. Excludes abandoned tasks from the list (stats header still includes them).

📋 Tasks 3/7 done | ◉2 in-progress ○1 pending ✗1 failed
  ◉ task-001 Implement auth...   ◉ task-003 Write API endp...   ○ task-004 Add rate limiti...
  ✗ task-005 Deploy to stag...   ⊘ task-006 Run integration...                      /tasks less

Toggle

Alt+T toggles the HUD on/off, preserving the current mode.

Idle Polling

The extension polls the task file every 30 seconds (configurable via DEFAULT_CONFIG.polling.idleIntervalSeconds) to detect changes made by other sessions or external processes. When changes are detected, the widget is automatically refreshed — including showing the widget if it was hidden and tasks now exist, or hiding it if all tasks were cleared.

Architecture

src/
├── index.ts          # Extension entry: tool, commands, shortcuts, lifecycle
├── tool.ts           # Tool action dispatcher (12 actions)
├── widget.ts         # HUD renderers (less/more modes)
├── overlay.ts        # Interactive overlay (list/detail/filter screens)
├── commands.ts       # Slash command implementations
└── engine/
    ├── index.ts      # Engine barrel export
    ├── crud.ts       # Create, read, update, list, delete
    ├── state-machine.ts  # State transitions with validation
    ├── dag.ts        # Dependency validation, cycle detection
    ├── notes.ts      # Note append with timestamps
    └── locking.ts    # PID-based lock management (via @pi-orca/core)

Test Coverage

86+ tests across 6 test files:

• crud.test.ts — CRUD operations, frontmatter parsing
• state-machine.test.ts — All state transitions, error cases
• dag.test.ts — Cycle detection, cascading, transitive deps
• locking.test.ts — Lock/unlock, PID detection
• notes.test.ts — Note append, timestamp, resumption
• integration.test.ts — End-to-end tool dispatcher flows
• widget.test.ts — HUD mode rendering, multi-column layout

Dependencies

• @pi-orca/core — Shared types, utilities, filesystem helpers

License

MIT License — see LICENSE for details.