Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Work item generation and execution.
//!
//! Contains the flat parallelism infrastructure:
//! - `WorkItem` - unit of work for the thread pool
//! - `TaskKind::compute()` (in `tasks.rs`) - route each task to its computation
//! - `work_items_for_worktree()` / `work_items_for_branch()` - generate work items
//! - `ExpectedResults` - track expected results for timeout diagnostics
//! - `seed_skipped_task_defaults()` - conservative sentinels for skipped tasks
//!
//! ## Status field bookkeeping at spawn time
//!
//! `refresh_status_symbols` resolves each gate independently, reading that
//! gate's required fields on `ListItem` / `WorktreeData` as they become
//! `Some`. Tasks that *will* run are written by the drain as their results
//! arrive. Tasks that will *not* run (unborn branches skip commit-dependent
//! tasks, the column plan excludes them, branches with no worktree have no
//! worktree-only tasks) have their fields
//! seeded here via [`seed_skipped_task_defaults`] with conservative defaults
//! — otherwise the fields would stay `None` forever and their gate would
//! never resolve.
use std::sync::Arc;
use crossbeam_channel as chan;
use worktrunk::git::Repository;
use super::super::model::{ListItem, UpstreamStatus, WorkingTreeStatus};
use super::CollectOptions;
use super::tasks::TaskContext;
use super::types::{TaskError, TaskKind, TaskResult};
/// Tasks that require a valid commit SHA. Skipped for unborn branches (no commits yet).
/// Without this, these tasks would fail on the null OID and show as errors in the table.
///
/// `WorkingTreeDiff` runs `git diff-index HEAD` and `WorkingTreeConflicts` runs
/// `git merge-tree` against the worktree's HEAD SHA — both fail on a null OID
/// with `fatal: ambiguous argument 'HEAD'` / `fatal: 0000… is not a valid
/// object`. Their seed defaults (`None` for the diff, `Some(None)` for the
/// conflict probe) render as `·` placeholders, matching how the other
/// commit-dependent columns degrade on unborn worktrees.
const COMMIT_TASKS: &[TaskKind] = &[
TaskKind::AheadBehind,
TaskKind::CommittedTreesMatch,
TaskKind::HasFileChanges,
TaskKind::IsAncestor,
TaskKind::BranchDiff,
TaskKind::MergeTreeConflicts,
TaskKind::WouldMergeAdd,
TaskKind::CiStatus,
TaskKind::Upstream,
TaskKind::WorkingTreeDiff,
TaskKind::WorkingTreeConflicts,
];
// ============================================================================
// Work Item Dispatch (for flat parallelism)
// ============================================================================
/// A unit of work for the thread pool.
///
/// Each work item represents a single task to be executed. Work items are
/// collected upfront and then processed in parallel via Rayon's thread pool,
/// avoiding nested parallelism (Rayon par_iter → thread::scope).
#[derive(Clone)]
pub struct WorkItem {
pub ctx: TaskContext,
pub kind: TaskKind,
}
impl WorkItem {
/// Execute this work item, returning the task result.
pub fn execute(self) -> Result<TaskResult, TaskError> {
let result = self.kind.compute(self.ctx);
if let Ok(ref task_result) = result {
debug_assert_eq!(TaskKind::from(task_result), self.kind);
}
result
}
}
// ============================================================================
// Expected Results Tracking
// ============================================================================
/// Tracks expected result types per item for timeout diagnostics.
///
/// Populated at spawn time so we know exactly which results to expect,
/// without hardcoding result lists that could drift from the spawn functions.
#[derive(Default)]
pub(crate) struct ExpectedResults {
inner: std::sync::Mutex<Vec<Vec<TaskKind>>>,
}
impl ExpectedResults {
/// Record that we expect a result of the given kind for the given item.
/// Called by `work_items_for_worktree()` / `work_items_for_branch()`.
pub fn expect(&self, item_idx: usize, kind: TaskKind) {
let mut inner = self.inner.lock().unwrap();
if inner.len() <= item_idx {
inner.resize_with(item_idx + 1, Vec::new);
}
inner[item_idx].push(kind);
}
/// Total number of expected results (for progress display).
pub fn count(&self) -> usize {
self.inner.lock().unwrap().iter().map(|v| v.len()).sum()
}
/// Expected results for a specific item.
pub fn results_for(&self, item_idx: usize) -> Vec<TaskKind> {
self.inner
.lock()
.unwrap()
.get(item_idx)
.cloned()
.unwrap_or_default()
}
}
// ============================================================================
// Skipped Task Sentinels
// ============================================================================
/// Seed conservative defaults for a task that will not run for an item.
///
/// `refresh_status_symbols` keeps gates at `None` while their inputs are
/// unloaded, which renders as the `·` placeholder. For tasks that will
/// *never* run (a task no rendered column needs, unborn item missing
/// commit-dependent tasks), seeding a conservative
/// default up front lets the gate resolve normally instead of showing `·`
/// forever.
///
/// **Not seeded by this function:** `item.counts`. Seeding the ahead/behind
/// counts with `(0, 0)` would falsely claim "in sync" in JSON output
/// (`JsonMain` / `JsonDefaultBranch`). Callers that need to resolve gate 3
/// (main_state) for items without counts should instead pre-seed
/// `status_symbols.main_state` directly — see [`seed_unborn_main_state`].
///
/// **Seeds are recorded on [`ListItem::seeded`]**: several seeded fields DO
/// reach schema-2 JSON (`orphan`, `upstream`, `merge_conflicts`, the
/// integration signals), where a conservative default would read as a
/// determined fact. `json_v2` consults the flags and emits null
/// (undetermined) for seeded families; the table keeps rendering the
/// conservative value.
///
/// Non-status-feeding tasks (`BranchDiff`, `CiStatus`, `UrlStatus`,
/// `SummaryGenerate`) are rendered by their own columns with their own
/// placeholders; `refresh_status_symbols` doesn't read them, so there is
/// nothing to seed.
pub(super) fn seed_skipped_task_defaults(item: &mut ListItem, kind: TaskKind) {
match kind {
// Not consumed by refresh_status_symbols — columns handle their own
// loading state.
TaskKind::BranchDiff
| TaskKind::CiStatus
| TaskKind::UrlStatus
| TaskKind::SummaryGenerate => {}
TaskKind::AheadBehind => {
// Seed `is_orphan` but NOT `counts` (leaks to JSON as a false
// "in sync"). Gate 3 callers that need counts-less resolution
// use `seed_unborn_main_state` to pre-seed
// `status_symbols.main_state` directly.
item.is_orphan = Some(false);
item.seeded.orphan = true;
}
TaskKind::Upstream => {
// `UpstreamStatus::default()` has `remote: None`, so `active()`
// returns `None` and the upstream renders as "no upstream".
item.upstream = Some(UpstreamStatus::default());
item.seeded.upstream = true;
}
TaskKind::CommittedTreesMatch => {
// Conservative: don't claim integrated if we haven't checked.
item.committed_trees_match = Some(false);
item.seeded.integration = true;
}
TaskKind::HasFileChanges => {
// Conservative: assume unique changes exist.
item.has_file_changes = Some(true);
item.seeded.integration = true;
}
TaskKind::WouldMergeAdd => {
// Conservative: assume the merge would add changes.
item.would_merge_add = Some(true);
item.is_patch_id_match = Some(false);
item.seeded.integration = true;
}
TaskKind::IsAncestor => {
// Conservative: don't claim merged if we haven't checked.
item.is_ancestor = Some(false);
item.seeded.integration = true;
}
TaskKind::MergeTreeConflicts => {
item.has_merge_tree_conflicts = Some(false);
item.seeded.merge_conflicts = true;
}
TaskKind::UserMarker => {
item.user_marker = Some(None);
}
TaskKind::WorkingTreeDiff => {
// Do not seed. `working_tree_diff` feeds gate 3's `is_clean`
// check and flows into JSON output. Seeding `Some(default())`
// would misreport dirty worktrees as clean+removable and
// fabricate an empty diff in `--format=json`. Same rule as
// `item.counts`: leaks-to-JSON inputs stay `None`; the gate
// waits and renders `·`.
}
TaskKind::WorkingTreeConflicts => {
if let Some(data) = item.worktree_data_mut() {
// `Some(None)` = "task did not run, fall back to the
// committed-HEAD merge-tree check" — matches the semantics
// of a clean working tree under `--full`.
data.has_working_tree_conflicts = Some(None);
}
}
TaskKind::GitOperation => {
if let Some(data) = item.worktree_data_mut() {
data.git_operation = Some(None);
}
}
}
}
/// Pre-seed gate 3 (`main_state`) for unborn items whose `AheadBehind`
/// task will not run.
///
/// Gate 3's tier 4 requires `item.counts` to be loaded, but `item.counts`
/// is a JSON-leaking field we can't safely seed. For unborn items there is
/// no ahead/behind relationship to compute — the main worktree always
/// resolves to `MainState::IsMain`, and a linked unborn worktree (rare:
/// `git worktree add -b new main` before the first commit) resolves to
/// `MainState::None` (no symbol). Both are known at spawn time without
/// any task output.
pub(super) fn seed_unborn_main_state(item: &mut ListItem) {
let is_main = item.is_main();
item.status_symbols.main_state = Some(if is_main {
super::super::model::MainState::IsMain
} else {
super::super::model::MainState::None
});
}
/// Pre-seed every gate on a prunable worktree so the only visible symbol
/// is `⊟` (from the metadata `worktree_state`).
///
/// Prunable worktrees have lost their directory or its `.git`, so no task
/// can run for them. Without this seeding, every gate would stay `None`
/// forever and the cell would render as seven `·` placeholders.
pub(super) fn seed_prunable_item(item: &mut ListItem) {
use super::super::model::{
Divergence, MainState, OperationState, StatusSymbols, WorktreeState,
};
item.status_symbols = StatusSymbols {
working_tree: Some(WorkingTreeStatus::default()),
operation_state: Some(OperationState::None),
worktree_state: Some(WorktreeState::Prunable),
main_state: Some(MainState::None),
upstream_divergence: Some(Divergence::None),
user_marker: Some(None),
};
}
// ============================================================================
// Work Item Generation
// ============================================================================
/// Generate work items for a worktree.
///
/// Returns a list of work items representing all tasks that should run for
/// this worktree. Expected results are registered internally as each work
/// item is added. The caller is responsible for executing the work items.
///
/// **Side effects on `item`:**
/// - Seeds conservative sentinels on fields corresponding to tasks that will
/// *not* run (unborn/skipped). See module docstring.
///
/// **Side effects on `tx`:**
/// - Sends an immediate `TaskResult::UrlStatus { url: Some, active: None }`
/// for items with a URL template, so the row redraws as soon as the
/// first drain tick fires (the slower follow-up `UrlStatus` health
/// check then updates `url_active`). The drain pipeline is the only
/// path that triggers progressive row redraws, so writing `item.url`
/// directly here would leave it stuck behind whatever task happens to
/// complete first.
///
/// Task preconditions (unborn branch, missing llm_command) are
/// enforced here — not in callers. This function is called from both
/// `collect()` and `populate_item()`, so guards must live here to cover all
/// entry points.
///
/// The `repo` parameter is cloned into each TaskContext, sharing its cache
/// via Arc.
pub fn work_items_for_worktree(
repo: &Repository,
item_idx: usize,
options: &CollectOptions,
expected_results: &Arc<ExpectedResults>,
tx: &chan::Sender<Result<TaskResult, TaskError>>,
item: &mut ListItem,
) -> Vec<WorkItem> {
// Prunable worktrees have lost their directory or its `.git` — no task
// can run.
// Seed every gate directly so the cell shows just the `⊟` metadata
// symbol rather than seven `·` placeholders.
if item.worktree_data().is_some_and(|data| data.is_prunable()) {
seed_prunable_item(item);
return vec![];
}
let run = &options.tasks;
let include_url = run.contains(&TaskKind::UrlStatus);
// Expand URL template for this item (only if URL status is enabled).
let item_url = if include_url {
options.url_template.as_ref().and_then(|template| {
item.branch().and_then(|branch| {
let mut vars = std::collections::HashMap::new();
vars.insert("branch", branch);
worktrunk::config::expand_template(
template,
&vars,
worktrunk::shell_exec::ShellEscapeMode::Literal,
repo,
"url-template",
)
.ok()
})
})
} else {
None
};
// Send the URL through the drain channel so the row redraws as soon as
// the result is processed. Without this round trip, the URL would only
// appear when *some other* task happens to complete and trigger a
// refresh — often the slow URL-status task itself.
if include_url && let Some(ref url) = item_url {
expected_results.expect(item_idx, TaskKind::UrlStatus);
let _ = tx.send(Ok(TaskResult::UrlStatus {
item_idx,
url: Some(url.clone()),
active: None,
}));
}
let ctx = TaskContext {
repo: repo.clone(),
branch_ref: item.branch_ref().clone(),
item_idx,
item_url,
llm_command: options.llm_command.clone(),
default_branch: options.default_branch.clone(),
integration_targets: options.integration_targets.clone(),
snapshot: options.snapshot.clone(),
};
let has_commits = item.head() != worktrunk::git::NULL_OID;
let mut items = Vec::with_capacity(15);
for kind in [
TaskKind::AheadBehind,
TaskKind::CommittedTreesMatch,
TaskKind::HasFileChanges,
TaskKind::IsAncestor,
TaskKind::Upstream,
TaskKind::WorkingTreeDiff,
TaskKind::GitOperation,
TaskKind::UserMarker,
TaskKind::WorkingTreeConflicts,
TaskKind::BranchDiff,
// The merge-tree conflict task peeks the shared porcelain cache and
// skips its own merge-tree call when the working-tree conflict task
// will produce an authoritative dirty-tree result.
TaskKind::MergeTreeConflicts,
TaskKind::CiStatus,
TaskKind::WouldMergeAdd,
TaskKind::SummaryGenerate,
] {
let will_skip = !run.contains(&kind) || (!has_commits && COMMIT_TASKS.contains(&kind));
if will_skip {
seed_skipped_task_defaults(item, kind);
continue;
}
expected_results.expect(item_idx, kind);
items.push(WorkItem {
ctx: ctx.clone(),
kind,
});
}
// Unborn items: their `AheadBehind` task was skipped in the loop
// above, so `item.counts` stays `None` (by design — seeding it would
// leak `{ahead:0, behind:0}` into JSON). Pre-seed `main_state`
// directly so gate 3 resolves without needing counts.
if !has_commits {
seed_unborn_main_state(item);
}
// URL status health check task (if we have a URL). Only this single
// work item is queued per item — the immediate `UrlStatus` placeholder
// was already sent through the drain channel above (never written to
// `item.url` directly; see the `work_items_for_worktree` docstring), so this task needs no
// additional placeholder send.
if include_url && ctx.item_url.is_some() {
expected_results.expect(item_idx, TaskKind::UrlStatus);
items.push(WorkItem {
ctx: ctx.clone(),
kind: TaskKind::UrlStatus,
});
}
items
}
/// Generate work items for a branch (no worktree).
///
/// Returns a list of work items representing all tasks that should run for this
/// branch. Branches have fewer tasks than worktrees (no working tree operations).
///
/// Task preconditions are enforced here, same as [`work_items_for_worktree`].
///
/// The `repo` parameter is cloned into each TaskContext, sharing its cache via Arc.
/// The item's [`BranchRef`](worktrunk::git::BranchRef) already records whether
/// it is local or remote, so this layer does not reconstruct ref qualification.
pub fn work_items_for_branch(
repo: &Repository,
item_idx: usize,
options: &CollectOptions,
expected_results: &Arc<ExpectedResults>,
item: &mut ListItem,
) -> Vec<WorkItem> {
let run = &options.tasks;
let ctx = TaskContext {
repo: repo.clone(),
branch_ref: item.branch_ref().clone(),
item_idx,
item_url: None, // Branches without worktrees don't have URLs
llm_command: options.llm_command.clone(),
default_branch: options.default_branch.clone(),
integration_targets: options.integration_targets.clone(),
snapshot: options.snapshot.clone(),
};
let mut items = Vec::with_capacity(11);
for kind in [
TaskKind::AheadBehind,
TaskKind::CommittedTreesMatch,
TaskKind::HasFileChanges,
TaskKind::IsAncestor,
TaskKind::Upstream,
TaskKind::BranchDiff,
TaskKind::MergeTreeConflicts,
TaskKind::CiStatus,
TaskKind::WouldMergeAdd,
TaskKind::SummaryGenerate,
] {
if !run.contains(&kind) {
seed_skipped_task_defaults(item, kind);
continue;
}
expected_results.expect(item_idx, kind);
items.push(WorkItem {
ctx: ctx.clone(),
kind,
});
}
// `UserMarker` is never in the branch task list above (it only runs
// for worktrees), but the user-marker gate of `refresh_status_symbols`
// *does* read `item.user_marker` and leaves position 6 unresolved while
// it is `None`. Seed it here so the marker gate resolves for branches.
seed_skipped_task_defaults(item, TaskKind::UserMarker);
// `WorkingTreeDiff` / `WorkingTreeConflicts` / `GitOperation` feed
// worktree-specific inputs; for branches the gates that read them
// resolve via dedicated `ItemKind::Branch` arms in
// `refresh_status_symbols`, never reading these fields. Seeding them is
// a no-op today (the seed helper branches on `ItemKind::Worktree`
// internally) but makes the per-item task set explicit and keeps this
// loop forward-compatible if the branch path ever starts reading them.
for kind in [
TaskKind::WorkingTreeDiff,
TaskKind::WorkingTreeConflicts,
TaskKind::GitOperation,
] {
seed_skipped_task_defaults(item, kind);
}
items
}
#[cfg(test)]
mod tests {
use super::*;
use crate::commands::list::collect::build_worktree_item;
use worktrunk::git::WorktreeInfo;
/// Every seed arm must point the negative direction: `json_v2` trusts a
/// positive `check_integration` match even when sibling signals were
/// seeded, which is only sound while no seed can fabricate a match.
#[test]
fn test_seeds_never_fabricate_integration() {
use strum::IntoEnumIterator;
use worktrunk::git::{IntegrationSignals, check_integration};
for kind in TaskKind::iter() {
let mut item = ListItem::new_branch("a".repeat(40), "feature".to_string());
seed_skipped_task_defaults(&mut item, kind);
let signals = IntegrationSignals {
is_same_commit: item.counts.map(|c| c.ahead == 0 && c.behind == 0),
is_ancestor: item.is_ancestor,
has_added_changes: item.has_file_changes,
trees_match: item.committed_trees_match,
would_merge_add: item.would_merge_add,
is_patch_id_match: item.is_patch_id_match,
};
assert!(
check_integration(&signals).is_none(),
"{kind:?} seed must not fabricate an integration match"
);
}
}
/// Producer → consumer: seeding marks the fact families, and schema-2
/// JSON reports them as null (undetermined) rather than presenting the
/// conservative defaults as determined facts.
#[test]
fn test_seeded_families_serialize_as_null() {
use strum::IntoEnumIterator;
use crate::commands::list::json_v2::JsonItemV2;
use crate::commands::list::model::{AheadBehind, Collected};
// Seed every skippable task on one item — the drain-timeout worst
// case — then load counts (never seeded) so the integration signals
// are all `Some`: without the flags this would read as determined
// not-integrated.
let mut item = ListItem::new_branch("a".repeat(40), "feature".to_string());
for kind in TaskKind::iter() {
seed_skipped_task_defaults(&mut item, kind);
}
item.counts = Some(AheadBehind {
ahead: 1,
behind: 0,
});
let mut all_vars = std::collections::HashMap::new();
let json = serde_json::to_value(JsonItemV2::from_list_item(
&item,
&mut all_vars,
Some("main"),
Collected::default(),
None,
&[],
))
.unwrap();
let db = &json["default_branch"];
assert!(db["orphan"].is_null(), "seeded orphan must be null");
assert!(
db["merge_conflicts"].is_null(),
"seeded merge_conflicts must be null"
);
assert!(
db.get("integration").is_some_and(|v| v.is_null()),
"seeded integration must be null"
);
assert!(
json.get("upstream").is_some_and(|v| v.is_null()),
"seeded upstream must be null"
);
}
#[test]
fn test_skip_url_status_suppresses_placeholder_and_task() {
let test = worktrunk::testing::TestRepo::new();
let repo = Repository::at(test.path()).expect("repo");
let wt = WorktreeInfo {
path: test.path().to_path_buf(),
head: "deadbeef".to_string(),
branch: Some("main".to_string()),
bare: false,
detached: false,
locked: None,
prunable: None,
};
// The `url` column isn't rendered (gate off), so UrlStatus isn't planned
// — even though a template is configured.
let gates = crate::commands::list::columns::ColumnGates {
show_full: true,
summary_enabled: true,
has_llm_command: true,
has_url_template: false,
};
let options = CollectOptions {
url_template: Some("http://localhost/{{ branch }}".to_string()),
..CollectOptions::for_columns(crate::commands::list::columns::all_columns(), &gates)
};
let expected_results = Arc::new(ExpectedResults::default());
let (tx, rx) = chan::unbounded::<Result<TaskResult, TaskError>>();
let mut item = build_worktree_item(&wt, true, false, false);
let items = work_items_for_worktree(&repo, 0, &options, &expected_results, &tx, &mut item);
// No placeholder UrlStatus result was sent to the channel.
assert!(rx.try_recv().is_err());
// No UrlStatus work item created
assert!(!items.iter().any(|w| w.kind == TaskKind::UrlStatus));
// No UrlStatus in expected results
assert!(
!expected_results
.results_for(0)
.contains(&TaskKind::UrlStatus)
);
// item_url is None for all items
assert!(items.iter().all(|w| w.ctx.item_url.is_none()));
}
// No spawn-level test for "no LLM → no Summary": the column plan is the
// single authority, and `test_required_tasks_for_render` pins that the gate
// drops SummaryGenerate when no LLM is configured. The spawn loop's "skip
// what isn't planned" rule is covered by the UrlStatus test above. If a
// caller plans Summary without a command anyway, the summary-generation task
// returns a clean error rather than misbehaving (tasks.rs).
}