feat: add supervisor-helper.sh with SQLite schema and state machine (t128.1)

[marcusquinn]

Summary

• Implements t128.1: Supervisor SQLite schema and state machine for the Autonomous Supervisor Loop (t128)
• Creates supervisor-helper.sh with full SQLite-backed task orchestration
• Foundation for t128.2 (worker dispatch), t128.3 (outcome evaluation), and subsequent subtasks

What's New

supervisor-helper.sh (~700 lines)

SQLite Schema (4 tables):

• tasks - Task queue with status, session, worktree, branch, retries, model, PR URL
• batches - Named batch groups with configurable concurrency limits
• batch_tasks - Many-to-many relationship with position ordering
• state_log - Full audit trail of every state transition with timestamps

State Machine (9 states, 18 valid transitions):

queued -> dispatched -> running -> evaluating -> complete
                                -> retrying   -> dispatched (retry cycle)
                                -> blocked    (needs human input)
                                -> failed     (max retries exceeded)

Commands (12):

• init - Initialize database
• add <task_id> - Add task (auto-detects description from TODO.md)
• batch <name> - Create batch with concurrency control
• transition <id> <state> - Validated state transitions with audit log
• status [id] - Task, batch, or overall status with color output
• list - Filter by state/batch, JSON output support
• next [batch_id] - Concurrency-aware next-task selection
• running-count - Active task count for semaphore checks
• reset - Reset terminal tasks back to queued
• cancel - Cancel task or entire batch (cascading)
• db [sql] - Direct SQLite access for debugging

Quality

• Zero ShellCheck violations
• local var="$1" pattern throughout
• Explicit returns in all functions
• WAL mode + busy_timeout for concurrent access
• Foreign keys with ON DELETE CASCADE

Also Updated

• subagent-index.toon - Registered supervisor-helper.sh
• README.md - Updated script count (165 -> 167), added Supervisor to orchestration table

Summary by CodeRabbit

• New Features
  • Added autonomous task orchestration system for managing multi-task workflows with persistent state tracking
  • Introduced batch processing capabilities with configurable concurrency control
  • Added comprehensive task management commands for creation, status monitoring, and lifecycle control
  • Included detailed state history logging for transparency and auditability

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[github-actions]

🔍 Code Quality Report

�[0;35m[MONITOR]�[0m Code Review Monitoring Report

�[0;34m[INFO]�[0m Latest Quality Status:
SonarCloud: 0 bugs, 0 vulnerabilities, 7 code smells

�[0;34m[INFO]�[0m Recent monitoring activity:
Fri Feb 6 04:13:48 UTC 2026: Code review monitoring started
Fri Feb 6 04:13:49 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 7
Fri Feb 6 04:13:49 UTC 2026: Qlty - 0 issues found, auto-formatting applied
Fri Feb 6 04:13:51 UTC 2026: Codacy analysis completed with auto-fixes

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 7
• VULNERABILITIES: 0

Generated on: Fri Feb 6 04:13:54 UTC 2026

---

Generated by AI DevOps Framework Code Review Monitoring

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

A new self-contained Bash-based supervisor script introduces multi-task orchestration with SQLite state persistence, supporting task creation, batching, state machine transitions, concurrency management, and comprehensive status tracking. Documentation and script index updated accordingly.

Changes

Cohort / File(s)	Summary
Supervisor Implementation .agent/scripts/supervisor-helper.sh	Introduces 1134 lines of Bash-based supervisor orchestration with SQLite persistence. Implements core commands (init, add, batch, transition, status, list, next, running-count, reset, cancel, db) supporting state machine validation, batch concurrency control, task metadata tracking, and state history logging. Includes database schema with tasks, batches, batch_tasks, and state_log tables, plus helper utilities for SQL escaping and schema management.
Documentation Updates .agent/subagent-index.toon, README.md	Script index entry added for supervisor-helper.sh with command descriptions. README updated to document new Supervisor component in Multi-Agent Orchestration architecture, reflecting role in autonomous task orchestration and SQLite state machine management. Helper script count incremented from 165 to 167.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as supervisor-helper.sh
    participant SQLite as SQLite DB
    participant StateLog as state_log table

    User->>CLI: init
    CLI->>SQLite: CREATE schema (tasks, batches, etc.)
    SQLite-->>CLI: Database ready

    User->>CLI: add task (description, model)
    CLI->>SQLite: INSERT task (state=queued)
    SQLite-->>CLI: task_id
    CLI->>StateLog: Log initial state
    StateLog-->>CLI: Recorded

    User->>CLI: batch --concurrency 3
    CLI->>SQLite: INSERT batch
    SQLite-->>CLI: batch_id

    User->>CLI: transition task_id running
    CLI->>SQLite: Validate state transition
    SQLite-->>CLI: Transition allowed
    CLI->>SQLite: UPDATE task state
    CLI->>StateLog: Log state change
    StateLog-->>CLI: Recorded
    CLI->>SQLite: Check batch completion
    SQLite-->>CLI: Status

    User->>CLI: status
    CLI->>SQLite: SELECT tasks, batches, state history
    SQLite-->>CLI: Results
    CLI-->>User: Colorized status output

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

📋✨ A supervisor rises with SQLite grace,
Orchestrating tasks through state-machine space,
With batches and queues in crisp bash ballet,
Persistence and transitions light up the way,
From chaos to order—let workflows relay! 🚀

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/t128-1-supervisor-schema

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}