git.stella-ops.org/docs/modules/taskrunner/README.md

TaskRunner

Status: Implemented Source: src/TaskRunner/ Owner: Platform Team

Purpose

TaskRunner executes Task Packs deterministically with approvals, sealed-mode enforcement, and evidence capture. Provides orchestration for automated workflows with plan-hash binding, offline operation, and complete provenance generation (DSSE attestation + evidence bundle).

Components

Services:

• StellaOps.TaskRunner.WebService - HTTP API with plan hash validation and SSE log streaming
• StellaOps.TaskRunner.Worker - Run orchestration with retries, artifact capture, and attestation

Libraries:

• StellaOps.TaskRunner.Core - Execution graph builder, simulation engine, step state machine
• StellaOps.TaskRunner.Infrastructure - Storage adapters (PostgreSQL, file), artifact/object store clients

Configuration

See etc/task-runner.yaml.sample for configuration options.

Key settings:

• PostgreSQL connection (schemas: pack_runs, pack_run_logs, pack_artifacts)
• Authority integration (issuer, audiences, client credentials)
• Telemetry and OTLP endpoint
• Artifact storage paths
• Approval timeout and retry policies
• Sealed-mode network allowlists

API Surface

• POST /api/runs - Submit pack run (requires manifest, inputs, tenant context)
• GET /api/runs/{runId} - Retrieve run status and graph
• GET /api/runs/{runId}/logs - SSE stream of ordered log events
• GET /api/runs/{runId}/artifacts - List captured artifacts with digests
• POST /api/runs/{runId}/approve - Record approval gate decision
• POST /api/runs/{runId}/cancel - Cancel active run

Dependencies

• PostgreSQL (schemas: pack_runs, pack_run_logs, pack_artifacts)
• Authority (authentication and approval token claims)
• Attestor (DSSE attestation generation)
• PacksRegistry (task pack manifests and modules)
• Scheduler (optional, for scheduled runs)

Related Documentation

• Architecture: ./architecture.md
• Task Packs Spec: ../../task-packs/ (if exists)
• Orchestrator: ../orchestrator/
• Attestor: ../attestor/

Current Status

Implemented with plan-hash binding and deterministic execution. Supports parallel/map steps, approval gates, policy gates, and the built-in bundle.ingest helper. Produces DSSE attestations for all completed runs.