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.