Tokio Async Code Review

Reviews tokio async runtime usage for task management, sync primitives, channel patterns, and runtime configuration. Covers Rust 2024 edition changes includi...

Security Scan

The skill's instructions and requirements mostly match a Tokio async code-review tool, but an ambiguous external dependency ("beagle-rust:review-verification-protocol") and a gate that requires loading it are unexplained and merit clarification before trusting the skill.

Purpose & Capability

Name, description, and content focus exclusively on reviewing Tokio/Rust async patterns (Cargo.toml, runtime setup, blocking calls, channels, sync primitives, task management). No unrelated binaries, credentials, or install steps are requested — the declared purpose aligns with requested capabilities.

Instruction Scope

Runtime instructions are detailed and confined to repository artifacts (Cargo.toml, source paths). However Gate #4 requires loading "beagle-rust:review-verification-protocol" before reporting findings; the SKILL.md does not explain what that is or where it comes from (local file, workspace crate, remote endpoint). This ambiguous external dependency could cause the agent to fetch or require files beyond the reviewed codebase and should be clarified.

Install Mechanism

No install spec and no code files to execute — instruction-only skill. This is the lowest-risk install profile; nothing is written to disk by an installer step.

Credentials

The skill declares no required environment variables, credentials, or config paths. Its intended operations (reading project files) are consistent with that minimal privilege model.

Persistence & Privilege

Flags are default (always:false, disable-model-invocation:false). The skill does not request persistent/system-wide privileges or modify other skills. Autonomous invocation is allowed by default (platform normal), which increases blast radius but is not itself a misconfiguration here.

What to consider before installing

This skill appears to be a focused, instruction-only Tokio async code reviewer and will read project files (Cargo.toml and source). Before installing or running it, ask the publisher what "beagle-rust:review-verification-protocol" refers to and where it is loaded from — the SKILL.md requires it for gate #4 but doesn't include or document it. If you cannot verify that protocol is a local, trusted artifact, avoid granting the skill access to private repositories or run it first in a sandboxed environment. Also confirm the skill will not transmit repository contents to any external service before invoking it automatically.

Review Workflow

1. Check Cargo.toml — Note tokio feature flags (full, rt-multi-thread, macros, sync, etc.). Missing features cause confusing compile errors.
2. Check runtime setup — Is #[tokio::main] or manual runtime construction used? Multi-thread vs current-thread?
3. Scan for blocking — Search for std::fs, std::net, std::thread::sleep, CPU-heavy loops in async functions.
4. Check channel usage — Match channel type to communication pattern (mpsc, broadcast, oneshot, watch).
5. Check sync primitives — Verify correct mutex type, proper guard lifetimes, no deadlock potential.

Gates (objective passes before conclusions)

Complete in order for the review scope. Do not assert Critical or Major until the relevant gate passes.

1. Dependency surface — Read the crate (and workspace, if inherited) Cargo.toml that supplies tokio. Pass: Written note of tokio version and enabled features, or explicit statement that there is no direct tokio dependency and where it comes from (workspace/path).
2. Runtime model — Locate runtime construction (#[tokio::main], Runtime::builder, tests, or library with no owned runtime). Pass: One line naming flavor (multi_thread / current_thread / tests-only / none) and where it is defined.
3. Blocking inventory — Search reviewed paths for blocking APIs (std::fs::, std::net:: without async wrappers, std::thread::sleep, heavy CPU loops in async fn). Pass: Each hit listed as path:line (or tool output excerpt), or explicit “no blocking patterns found in reviewed async code” after the search.
4. Protocol — Load beagle-rust:review-verification-protocol. Pass: Its pass conditions met before any finding is reported (file:line evidence for asserted issues).

Output Format

Report findings as:

[FILE:LINE] ISSUE_TITLE
Severity: Critical | Major | Minor | Informational
Description of the issue and why it matters.

Quick Reference

Issue Type	Reference
Task spawning, JoinHandle, structured concurrency	references/task-management.md
Mutex, RwLock, Semaphore, Notify, Barrier	references/sync-primitives.md
mpsc, broadcast, oneshot, watch channel patterns	references/channels.md
Pin, cancellation, Future internals, select!, blocking bridge	references/pinning-cancellation.md

Review Checklist

Runtime Configuration

• Tokio features in Cargo.toml match actual usage
• Runtime flavor matches workload (multi_thread for I/O-bound, current_thread for simpler cases)
• #[tokio::test] used for async tests (not manual runtime construction)
• Worker thread count configured appropriately for production

Task Management

• spawn return values (JoinHandle) are tracked, not silently dropped
• spawn_blocking used for CPU-heavy or synchronous I/O operations
• Tasks respect cancellation (via CancellationToken, select!, or shutdown channels)
• JoinError (task panic or cancellation) is handled, not just unwrapped
• tokio::select! branches are cancellation-safe
• Native async fn in traits used instead of async-trait crate where possible (stable since Rust 1.75)
• RPIT lifetime capture reviewed in async contexts — -> impl Future now captures all in-scope lifetimes in edition 2024

Sync Primitives

• tokio::sync::Mutex used when lock is held across .await; std::sync::Mutex for short non-async sections
• No mutex guard held across await points (deadlock risk)
• Semaphore used for limiting concurrent operations (not ad-hoc counters)
• RwLock used when read-heavy workload (many readers, infrequent writes)
• Notify used for simple signaling (not channel overhead)
• std::sync::LazyLock used instead of once_cell::sync::Lazy or lazy_static! for runtime-initialized singletons (stable since Rust 1.80)
• if let lock guard patterns reviewed for edition 2024 temporary scoping — temporaries drop earlier, may change borrow validity

Channels

• Channel type matches pattern: mpsc for back-pressure, broadcast for fan-out, oneshot for request-response, watch for latest-value
• Bounded channels have appropriate capacity (not too small = deadlock, not too large = memory)
• SendError / RecvError handled (indicates other side dropped)
• Broadcast Lagged errors handled (receiver fell behind)
• Channel senders dropped when done to signal completion to receivers

Timer and Sleep

• tokio::time::sleep used instead of std::thread::sleep
• tokio::time::timeout wraps operations that could hang
• tokio::time::interval used correctly (.tick().await for periodic work)

Severity Calibration

Critical

• Blocking I/O (std::fs::read, std::net::TcpStream) in async context without spawn_blocking
• Mutex guard held across .await point (deadlock potential)
• std::thread::sleep in async function (blocks runtime thread)
• Unbounded channel where back-pressure is needed (OOM risk)

Major

• JoinHandle silently dropped (lost errors, zombie tasks)
• Missing select! cancellation safety consideration
• Wrong mutex type (std vs tokio) for the use case
• Missing timeout on network/external operations

Minor

• tokio::spawn for trivially small async blocks (overhead > benefit)
• Overly large channel buffer without justification
• Manual runtime construction where #[tokio::main] suffices
• std::sync::Mutex where contention is high enough to benefit from tokio's async mutex

Informational

• Suggestions to use tokio-util utilities (e.g., CancellationToken)
• Tower middleware patterns for service composition
• Structured concurrency with JoinSet
• Migration from async-trait crate to native async fn in traits
• Migration from once_cell / lazy_static to std::sync::LazyLock
• Using #[expect(lint)] instead of #[allow(lint)] for self-cleaning suppression

Valid Patterns (Do NOT Flag)

• std::sync::Mutex for short critical sections — tokio docs recommend this when no .await is inside the lock
• tokio::spawn without explicit join — Valid for background tasks with proper shutdown signaling
• Unbuffered channel capacity of 1 — Valid for synchronization barriers
• #[tokio::main(flavor = "current_thread")] in simple binaries — Not every app needs multi-thread runtime
• clone() on Arc<T> before spawn — Required for moving into tasks, not unnecessary cloning
• Large broadcast channel capacity — Valid when lagged errors are expensive (event sourcing)
• Native async fn in traits without async-trait — Stable since 1.75; the crate is still valid for dyn dispatch cases
• + use<'a> on -> impl Future returns — Correct edition 2024 precise capture syntax to limit lifetime capture
• #[expect(clippy::type_complexity)] on complex async types — Self-cleaning alternative to #[allow], warns when suppression is no longer needed

Before Submitting Findings

After Gates, apply beagle-rust:review-verification-protocol to every reported issue (evidence and dispositions per that skill).