Concept
Tasks
A task is a unit of work in Tanjiren. It carries an intent (what you want done), a mode (how to execute it), target workstations, optional approval gates, and a full execution lifecycle with leases, logs, and artifacts.
Three execution modes
Command (run a shell command), Prompt (send an AI prompt), or Investigate (structured investigation with questions).
Approval gates
Doctrine can require human approval before execution. Approvals are scoped, time-limited, and single-use.
Lease-based execution
Only one worker can execute a task at a time. Workers hold a distributed lease that must be renewed via heartbeat.
Lifecycle
Every task follows a deterministic lifecycle with six possible states. The happy path goes from planned to queued to executing to completed.
Planned
Task is created. If doctrine requires approval, the task waits here with approval_status = pending. If no approval is needed, it transitions immediately to queued.
Queued
Task is ready for execution. An execution record and steps have been materialized. The task is waiting for a worker to claim it via heartbeat piggyback or direct assignment.
Executing
A worker has claimed the execution lease and is actively running the task. The worker sends heartbeats to keep the lease alive. Logs and events stream in real-time.
Completed
All steps have finished successfully. An outcome summary is generated and the lease is released. This is a terminal state.
Failed
One or more steps failed, or the task was rejected during approval. If retry policy is enabled, a new attempt may be scheduled automatically.
Cancelled
An operator cancelled the task. The lease is released and any running steps are terminated.
Execution modes
command
Execute a shell command on each target workstation. Exit code determines success or failure.
npm run build
prompt
Send an AI prompt to the agent running on the workstation. The agent processes it and returns a response.
Review the auth module for SQL injection vulnerabilities
investigate
Run a structured investigation with predefined questions. Results are captured as artifacts.
Investigate production error spike in /api/checkout
Approval gates
Organization doctrine can require human approval before a task executes. When doctrine evaluation determines that approval is needed, the task stays in the planned state until an admin or owner approves or rejects it.
| Approval class | When required |
|---|---|
| No approval needed. Task proceeds immediately. | |
| sensitive_write | Involves writing to infrastructure, databases, or sensitive systems. |
| production_mutation | Modifies production systems. Highest escalation tier. |
Approval tokens are single-use and time-limited (15 minutes by default). A snapshot of the current doctrine is stored with the task to ensure consistency.
Execution lease
When a worker claims a task, it acquires a distributed lease with a default TTL of 90 seconds. The lease is a mutual contract: the worker promises to send heartbeats, and the system promises not to reassign the task while the lease is alive.
Claim
Worker claims the lease. A fencing token (leaseGeneration) is incremented. TTL starts counting down.
Heartbeat
Worker extends the lease TTL every 30-60 seconds. The fencing token stays the same (no ownership transition).
Release
Worker voluntarily releases the lease when execution finishes. The fencing token is incremented again.
Recovery
If the worker disappears and the lease TTL expires, the lease is marked stale. A safety-net reconciliation process can then release it for retry.
The fencing token(leaseGeneration) prevents split-brain scenarios. Every mutation to the execution record uses a compare-and-swap check: if the generation doesn't match, the write is rejected. This ensures a zombie worker from a previous lease cannot corrupt the current execution.
Steps, logs, and artifacts
Each task is broken into steps — one per target workstation. Steps track individual execution progress, output previews, exit codes, and duration.
Logs are streaming output captured during execution (stdout and stderr). They are deduplicated by signature and stored for post-mortem analysis.
Artifacts are durable, user-curated findings attached to a task (or an investigation). They survive task completion and serve as the permanent record. Types include notes, links, evidence, and auto-generated summaries.
Scheduling
Tasks can be created on a schedule using cron expressions. A task schedule stores a task template (mode, intent, targets) and materializes new tasks at each cron tick.
The nextRunAt timestamp is precomputed to enable efficient queries. Each materialization creates a fresh task with a new ID, preserving full audit history.
Retry policy
Tasks can define a retry policy that automatically creates a new attempt when execution fails. The retry creates a new task linked to the original via retryOfTaskId and rootTaskId.
MCP tools and resources
| Tool | Scope | Description |
|---|---|---|
| list_tasks | mcp:read | List tasks with filters (status, mode, approval, worker, investigation) |
| get_task | mcp:read | Full task with execution, steps, artifacts, and approvals |
| create_task | mcp:operate | Create a new task with intent, mode, and targets |
| approve_task | mcp:operate | Approve a pending task for execution |
| reject_task | mcp:operate | Reject a pending task |
| cancel_task | mcp:operate | Cancel a running or queued task |
| retry_task | mcp:operate | Create a new attempt from a failed task |
| add_task_artifact | mcp:operate | Attach a note, link, or evidence to a task |
Resources
tanjiren://tasks/{id}Full task record with execution statetanjiren://tasks/runtime-overviewOrg-wide execution summary and statistics