feat: task scheduling, CLI commands, and task resumption (v0.4.0)

CLAUDE.md

@@ -55,6 +55,8 @@ npm run test:coverage       # With coverage
 - `QueueHandler` → dependency-aware task queueing
 - `WorkerHandler` → worker lifecycle
 - `PersistenceHandler` → database operations
+- `ScheduleHandler` → schedule lifecycle (create, pause, resume, cancel)
+- `ScheduleExecutor` → cron/one-time execution engine (note: has direct repo writes, architectural exception to pure event-driven pattern)
 
 See `docs/architecture/` for implementation details.
 
@@ -140,6 +142,8 @@ gh release create v{version} --notes-file docs/releases/RELEASE_NOTES_v{version}
 - SQLite with WAL mode for concurrent access
 - All mutations go through event handlers (PersistenceHandler, DependencyHandler)
 - Use synchronous transactions for TOCTOU protection (cycle detection)
+- `schedules` table: schedule definitions, cron/one-time config, status, timezone
+- `schedule_executions` table: execution history and audit trail
 
 ### Dependencies
 
@@ -150,7 +154,7 @@ When adding task dependencies:
 
 ### MCP Tools
 
-All tools use PascalCase: `DelegateTask`, `TaskStatus`, `TaskLogs`, `CancelTask`
+All tools use PascalCase: `DelegateTask`, `TaskStatus`, `TaskLogs`, `CancelTask`, `ScheduleTask`, `ListSchedules`, `GetSchedule`, `CancelSchedule`, `PauseSchedule`, `ResumeSchedule`
 
 ## File Locations
 
@@ -167,6 +171,10 @@ Quick reference for common operations:
 | Handler setup | `src/services/handler-setup.ts` |
 | MCP adapter | `src/adapters/mcp-adapter.ts` |
 | CLI | `src/cli.ts` |
+| Schedule repository | `src/implementations/schedule-repository.ts` |
+| Schedule handler | `src/services/handlers/schedule-handler.ts` |
+| Schedule executor | `src/services/schedule-executor.ts` |
+| Cron utilities | `src/utils/cron.ts` |
 
 ## Documentation Structure
 

README.md

@@ -20,6 +20,8 @@
 - **Intelligent Resource Management**: Monitors CPU and memory in real-time, spawning workers when resources are available
 - **Task Persistence & Recovery**: SQLite storage with automatic crash recovery
 - **Task Dependencies**: DAG-based dependency resolution with cycle detection
+- **Task Scheduling**: Cron and one-time scheduling with timezone support and missed run policies
+- **Task Resumption**: Resume failed/completed tasks with enriched context from automatic checkpoints
 
 See **[FEATURES.md](./docs/FEATURES.md)** for complete feature list.
 
@@ -73,6 +75,14 @@ Once configured, use these tools in Claude Code:
 | **TaskStatus** | Get real-time task status | `TaskStatus({ taskId })` |
 | **TaskLogs** | Stream or retrieve execution logs | `TaskLogs({ taskId })` |
 | **CancelTask** | Cancel tasks with resource cleanup | `CancelTask({ taskId, reason })` |
+| **RetryTask** | Retry a failed or completed task | `RetryTask({ taskId })` |
+| **ScheduleTask** | Schedule recurring or one-time tasks | `ScheduleTask({ prompt: "...", scheduleType: "cron", cronExpression: "0 2 * * *" })` |
+| **ListSchedules** | List schedules with optional status filter | `ListSchedules({ status: "active" })` |
+| **GetSchedule** | Get schedule details and execution history | `GetSchedule({ scheduleId })` |
+| **CancelSchedule** | Cancel an active schedule | `CancelSchedule({ scheduleId, reason })` |
+| **PauseSchedule** | Pause a schedule (resumable) | `PauseSchedule({ scheduleId })` |
+| **ResumeSchedule** | Resume a paused schedule | `ResumeSchedule({ scheduleId })` |
+| **ResumeTask** | Resume a failed/completed task with checkpoint context | `ResumeTask({ taskId, additionalContext? })` |
 
 ### CLI Commands
 
@@ -83,6 +93,14 @@ Once configured, use these tools in Claude Code:
 | `claudine status [task-id]` | Check task status (all tasks if no ID) |
 | `claudine logs <task-id>` | View task output |
 | `claudine cancel <task-id>` | Cancel running task |
+| `claudine schedule create <prompt>` | Create a cron or one-time schedule |
+| `claudine schedule list` | List schedules with optional status filter |
+| `claudine schedule get <id>` | Get schedule details and execution history |
+| `claudine schedule pause <id>` | Pause an active schedule |
+| `claudine schedule resume <id>` | Resume a paused schedule |
+| `claudine schedule cancel <id>` | Cancel a schedule |
+| `claudine pipeline <prompt> ...` | Create chained one-time schedules with delays |
+| `claudine resume <task-id>` | Resume a task from its checkpoint |
 | `claudine help` | Show help |
 
 ### Task Dependencies
@@ -117,8 +135,70 @@ const commit = await DelegateTask({
 });
 ```
 
+**Session continuation** (pass output context through dependency chains):
+
+```typescript
+// Build task runs first
+const build = await DelegateTask({ prompt: "npm run build" });
+
+// Test task receives build's output/git state in its prompt
+const test = await DelegateTask({
+  prompt: "npm test",
+  dependsOn: [build.taskId],
+  continueFrom: build.taskId
+});
+```
+
+When `continueFrom` is set, the dependent task's prompt is automatically enriched with the dependency's checkpoint context (output summary, git state, errors) before execution.
+
 See **[Task Dependencies Documentation](./docs/TASK-DEPENDENCIES.md)** for advanced patterns (diamond dependencies, error handling, failure propagation).
 
+### Task Scheduling
+
+Schedule tasks for future or recurring execution:
+
+```typescript
+// Recurring: daily backup at 2am EST
+await ScheduleTask({
+  prompt: "Backup database to S3",
+  scheduleType: "cron",
+  cronExpression: "0 2 * * *",
+  timezone: "America/New_York",
+  missedRunPolicy: "catchup"
+});
+
+// One-time: deploy tomorrow at 8am UTC
+await ScheduleTask({
+  prompt: "Deploy to production",
+  scheduleType: "one_time",
+  scheduledAt: "2026-02-19T08:00:00Z"
+});
+```
+
+**Schedule types**: `cron` (5-field expressions) and `one_time` (ISO 8601 datetime). **Missed run policies**: `skip`, `catchup`, `fail`. Supports IANA timezones and concurrent execution prevention.
+
+### Task Resumption
+
+Resume failed or completed tasks with enriched context from automatic checkpoints:
+
+```bash
+# Resume a failed task
+claudine resume task-abc123
+
+# Resume with additional instructions
+claudine resume task-abc123 --context "Try a different approach this time"
+```
+
+```typescript
+// Via MCP
+await ResumeTask({
+  taskId: "task-abc123",
+  additionalContext: "Focus on the database migration step"
+});
+```
+
+Checkpoints are captured automatically on task completion/failure, preserving git state (branch, SHA, dirty files) and the last 50 lines of output. Resumed tasks receive the full checkpoint context in their prompt and track lineage via `parentTaskId` and `retryOf` fields.
+
 ## Architecture
 
 **Event-driven system** with autoscaling workers and SQLite persistence. Components communicate through a central EventBus, eliminating race conditions and direct state management.
@@ -168,18 +248,26 @@ npm run dev        # Development mode with auto-reload
 npm run build      # Build TypeScript
 npm start          # Run built server
 npm run typecheck  # Type checking
-npm test           # Run tests
 npm run clean      # Clean build artifacts
 ```
 
 ### Testing
 
+Tests are grouped to prevent memory exhaustion. `npm test` is blocked as a safety measure.
+
 ```bash
-npm test                    # Run all tests (safe, sequential)
-npm run test:coverage       # Run with coverage
-npm run test:unit           # Unit tests only
-npm run test:integration    # Integration tests only
-npm run validate            # Validate entire setup
+# Grouped tests (fast, safe to run individually)
+npm run test:core           # Core domain logic (~3s)
+npm run test:handlers       # Service handlers (~3s)
+npm run test:repositories   # Data layer (~2s)
+npm run test:adapters       # MCP adapter (~2s)
+npm run test:implementations # Other implementations (~2s)
+npm run test:cli            # CLI tests (~2s)
+npm run test:integration    # Integration tests
+
+# Full suite (local terminal / CI only)
+npm run test:all            # All tests
+npm run test:coverage       # With coverage
 ```
 
 ### Project Structure
@@ -207,8 +295,9 @@ claudine/
 - [x] v0.2.1 - Event-driven architecture and CLI
 - [x] v0.2.3 - Stability improvements
 - [x] v0.3.0 - Task dependency resolution
-- [ ] v0.3.1 - Dependency performance optimizations
-- [ ] v0.4.0 - Task resumption and scheduling
+- [x] v0.3.2 - Settling workers and spawn burst protection
+- [x] v0.3.3 - Test infrastructure and memory management
+- [x] v0.4.0 - Task scheduling and task resumption
 - [ ] v0.5.0 - Distributed multi-server processing
 
 See **[ROADMAP.md](./docs/ROADMAP.md)** for detailed plans and timelines.

docs/FEATURES.md

@@ -1,8 +1,8 @@
-# Claudine v0.3.x - Current Features
+# Claudine Features
 
-This document lists all features that are **currently implemented and working** in Claudine v0.3.x.
+This document lists all features that are **currently implemented and working** in Claudine.
 
-Last Updated: November 2025
+Last Updated: February 2026
 
 ## ✅ Core Task Delegation
 
@@ -11,6 +11,7 @@ Last Updated: November 2025
 - **TaskStatus**: Check status of running/completed tasks
 - **TaskLogs**: Retrieve stdout/stderr output from tasks (with tail option)
 - **CancelTask**: Cancel running tasks with optional reason
+- **RetryTask**: Retry a failed or completed task (creates new task with same prompt)
 
 ### Task Management
 - **Priority Levels**: P0 (Critical), P1 (High), P2 (Normal)
@@ -118,12 +119,27 @@ Last Updated: November 2025
 - `claudine mcp config`: Show MCP configuration examples
 - `claudine help`: Show help and usage
 
-### Direct Task Commands (New in v0.2.1)
+### Direct Task Commands (v0.2.1+)
 - `claudine delegate <prompt>`: Delegate task directly to background Claude instance
 - `claudine status [task-id]`: Check status of all tasks or specific task
 - `claudine logs <task-id>`: Retrieve task output and logs
 - `claudine cancel <task-id> [reason]`: Cancel running task with optional reason
 
+### Schedule Commands (v0.4.0+)
+- `claudine schedule create <prompt> [options]`: Create a cron or one-time scheduled task
+- `claudine schedule list [--status <status>]`: List schedules with optional status filter
+- `claudine schedule get <id> [--history]`: Get schedule details and execution history
+- `claudine schedule pause <id>`: Pause an active schedule
+- `claudine schedule resume <id>`: Resume a paused schedule
+- `claudine schedule cancel <id> [reason]`: Cancel a schedule with optional reason
+
+### Pipeline Commands (v0.4.0+)
+- `claudine pipeline <prompt> [--delay Nm <prompt>]...`: Create chained one-time schedules with delays
+
+### Task Resumption Commands (v0.4.0+)
+- `claudine resume <task-id>`: Resume a failed/completed task from its checkpoint
+- `claudine resume <task-id> --context "..."`: Resume with additional instructions
+
 ### Configuration Examples
 - **NPM Package**: Global installation support
 - **Local Development**: Source code execution
@@ -167,23 +183,114 @@ Last Updated: November 2025
 - **Atomic Transactions**: TOCTOU-safe dependency addition with synchronous better-sqlite3 transactions
 - **Composite Indexes**: Optimized queries for dependency lookups and blocked task checks
 
+### Session Continuation (v0.4.0)
+- **`continueFrom` Field**: Dependent tasks can specify a dependency whose checkpoint context is injected into their prompt
+- **Automatic Enrichment**: When the dependency completes, its output summary, git state, and errors are prepended to the dependent task's prompt
+- **Race-Safe**: Subscribe-first pattern with 5-second timeout ensures checkpoint is available before task runs
+- **Validation**: `continueFrom` must reference a task in the `dependsOn` list (auto-added if missing)
+- **Chain Support**: A→B→C where B receives A's context and C receives B's (which includes A's)
+
 ### Event-Driven Integration
 - **TaskDependencyAdded**: Emitted when new dependency relationship created
 - **DependencyResolved**: Emitted when blocking dependency completes
 - **TaskUnblocked**: Emitted when all dependencies resolved, triggers automatic queuing
 
+## ✅ Task Scheduling (v0.4.0)
+
+### MCP Tools
+- **ScheduleTask**: Create recurring (cron) or one-time scheduled tasks
+- **ListSchedules**: List all schedules with optional status filter and pagination
+- **GetSchedule**: Get schedule details including execution history
+- **CancelSchedule**: Cancel an active schedule with optional reason
+- **PauseSchedule**: Pause an active schedule (can be resumed later)
+- **ResumeSchedule**: Resume a paused schedule
+
+### Schedule Types
+- **CRON**: Standard 5-field cron expressions for recurring task execution
+- **ONE_TIME**: ISO 8601 datetime for single future execution
+
+### Configuration
+- **Timezone Support**: IANA timezone identifiers (e.g., `America/New_York`) with DST awareness
+- **Missed Run Policies**: `skip` (ignore missed runs), `catchup` (execute missed runs), `fail` (mark as failed)
+- **Max Runs**: Optional limit on number of executions for cron schedules
+- **Expiration**: Optional ISO 8601 expiry datetime for schedules
+
+### Concurrent Execution Prevention
+- **Lock-Based Protection**: Prevents overlapping executions of the same schedule
+- **Execution Tracking**: Full history of schedule executions with status and timing
+
+### Event-Driven Integration
+- **ScheduleCreated**: Emitted when a new schedule is created
+- **ScheduleCancelled**: Emitted when a schedule is cancelled
+- **SchedulePaused**: Emitted when a schedule is paused
+- **ScheduleResumed**: Emitted when a schedule is resumed
+- **ScheduleExecuted**: Emitted when a scheduled task is triggered
+
+## ✅ Task Resumption (v0.4.0)
+
+### Auto-Checkpoints
+- **Automatic Capture**: Checkpoints created on task completion or failure (via `CheckpointHandler`)
+- **Git State**: Branch name, commit SHA, and dirty file list recorded at checkpoint time
+- **Output Summary**: Last 50 lines of stdout/stderr preserved for context injection
+- **Database Persistence**: `task_checkpoints` table (migration v5) with full audit data
+
+### Resume Workflow
+- **Enriched Prompts**: Resumed tasks receive full checkpoint context (previous output, git state, error info)
+- **Additional Context**: Provide extra instructions when resuming to guide the retry
+- **Retry Chains**: Track resume lineage via `parentTaskId` and `retryOf` fields on the new task
+- **Terminal State Requirement**: Only tasks in completed, failed, or cancelled states can be resumed
+
+### MCP Tool
+- **ResumeTask**: Resume a terminal task with optional `additionalContext` string (max 4000 chars)
+
+### Event-Driven Integration
+- **TaskCompleted / TaskFailed**: Triggers automatic checkpoint capture via `CheckpointHandler`
+- **CheckpointRepository**: SQLite persistence with prepared statements and Zod boundary validation
+
 ## ❌ NOT Implemented (Despite Some Documentation Claims)
 - **Distributed Processing**: Single-server only
 - **Web UI**: No dashboard interface
 - **Task Templates**: No preset task configurations
-- **Scheduled Tasks**: No cron-like scheduling
 - **Multi-User Support**: Single-user focused
 - **REST API**: MCP protocol only
 
 ---
 
 ---
 
+## 🆕 What's New in v0.4.0
+
+### Task Scheduling
+- **Cron & One-Time Schedules**: Standard 5-field cron expressions and ISO 8601 one-time scheduling
+- **Timezone Support**: IANA timezone identifiers with DST awareness
+- **Missed Run Policies**: `skip`, `catchup`, or `fail` for overdue triggers
+- **Lifecycle Management**: Pause, resume, cancel schedules with full execution history
+- **Concurrent Execution Prevention**: Lock-based protection against overlapping runs
+- **6 MCP Tools**: `ScheduleTask`, `ListSchedules`, `GetSchedule`, `CancelSchedule`, `PauseSchedule`, `ResumeSchedule`
+- **CLI + Pipeline**: Full CLI parity including `pipeline` command for chained one-time schedules
+
+### Task Resumption
+- **Auto-Checkpoints**: Captured on task completion/failure with git state and output summary
+- **Enriched Prompts**: Resumed tasks receive full context from previous attempt
+- **Retry Chains**: Track resume lineage via `parentTaskId` and `retryOf` fields
+- **MCP Tool**: `ResumeTask` with optional additional context
+- **CLI**: `claudine resume <task-id> [--context "..."]`
+
+### Session Continuation (`continueFrom`)
+- **Dependency Context Injection**: Dependent tasks receive checkpoint context from a specified dependency
+- **`continueFrom` Field**: Added to `DelegateTask` MCP tool and `--continue-from` CLI flag
+- **Automatic Enrichment**: Output summary, git state, and errors prepended to task prompt
+- **Race-Safe Design**: Subscribe-first pattern ensures checkpoint availability before task execution
+- **Chain Support**: Context flows through A→B→C dependency chains
+
+### Infrastructure
+- **Schedule Service Extraction**: ~375 lines of business logic extracted from MCP adapter for CLI reuse
+- **CLI Bootstrap Helper**: `withServices()` eliminates repeated bootstrap boilerplate
+- **Database Migrations v3-v6**: `schedules`, `schedule_executions`, `task_checkpoints` tables, `continue_from` column
+- **FK Cascade Fix**: Separated `save()` from `update()` to prevent cascade data loss
+
+---
+
 ## 🆕 What's New in v0.2.1
 
 ### Event-Driven Architecture
@@ -192,7 +299,7 @@ Last Updated: November 2025
 - **Event Handlers**: Specialized handlers for different concerns (persistence, queue, workers, output)
 - **Zero Direct State**: TaskManager is stateless, handlers manage all state via events
 
-### Direct CLI Commands  
+### Direct CLI Commands
 - **Task Management**: Direct CLI interface without MCP connection required
 - **Real-time Testing**: Instant task delegation and status checking
 - **Better DX**: No need to reconnect MCP server for testing
@@ -204,4 +311,4 @@ Last Updated: November 2025
 
 ---
 
-**Note**: This document reflects the actual implemented features as of v0.3.x. For planned features, see [ROADMAP.md](./ROADMAP.md).
+**Note**: This document reflects the actual implemented features. For planned features, see [ROADMAP.md](./ROADMAP.md).