write-capable sub-agent launch requires a durable coordinati

Error message

write-capable sub-agent launch requires a durable coordination state path

What it means

Launching a write-capable sub-agent (profile permissions.write == true) requires durable coordination state: if the manager's coordination process lock is required (shared-workspace contention control) but no durable state_path is configured, the spawn is refused before launch. The guarantee being protected: write contention receipts and worker registration must survive a crash, which is impossible without a durable path.

Source

Thrown at crates/tui/src/tools/subagent/mod.rs:6353

                    &tool_profile,
                    &agent.model,
                    options.model_route.clone(),
                    options.write_claim.is_some(),
                );
                runtime.worker_profile = profile.clone();
                profile
            }
        };
        let write_capable = runtime_profile.permissions.write;
        if write_capable {
            // Isolated-worktree children mutate their own checkout, so they
            // do not contend for the shared-workspace process lock (#5036).
            if !options.isolated_worktree {
                self.ensure_coordination_process_lock()
                    .map_err(anyhow::Error::msg)?;
            }
            if self.coordination_process_lock_required && self.state_path.is_none() {
                return Err(anyhow!(
                    "write-capable sub-agent launch requires a durable coordination state path"
                ));
            }
        }
        let durable_launch_snapshot =
            write_capable.then(|| (self.worker_records.clone(), self.coordination.clone()));
        let persisted_claim = if write_capable {
            options
                .write_claim
                .clone()
                .map(|mut claim| {
                    claim.owner = agent_id.clone();
                    let claim = if options.claim_pre_namespaced {
                        claim
                    } else {
                        self.namespace_write_claim(
                            &agent.workspace,
                            options.isolated_worktree,

View on GitHub (pinned to 0c42157ee5)

Solutions

Configure a durable coordination state path for the manager (the app wires state_path from its persistent state directory; embeddings must pass one at construction instead of the in-memory default)
Spawn write-capable children with isolated_worktree set — isolated worktree children mutate their own checkout and skip the shared-workspace lock requirement
Keep the sub-agent read-only (permissions.write = false) if durable coordination is genuinely unavailable

Example fix

// before (in-memory manager, write-capable spawn fails)
let manager = SubAgentManager::new(/* ... */); // state_path: None
manager.spawn_subagent_from_input(&write_request).await?; // refuses

// after
let manager = SubAgentManager::new(/* ... */)
    .with_state_path(state_dir.join("subagents/state.json"));
manager.spawn_subagent_from_input(&write_request).await?;

Defensive patterns

Strategy: validation

Validate before calling

// Before spawning writers on a shared workspace, ensure durable state exists.
anyhow::ensure!(
    state_path.join("subagents/state.json").exists(),
    "write-capable children need a durable coordination state path; \
     configure the state directory or use isolated worktrees"
);

Try / catch

Catch 'requires a durable coordination state path' as a configuration error: stop the spawn path, surface a setup instruction, and re-run after the state path is configured — retrying without config change always fails.

Prevention

Wire a persistent state directory into the manager at construction whenever write-permission profiles are enabled
Smoke-test one write-capable spawn at startup to fail fast on missing configuration
Default orchestration templates to isolated-worktree children for any task that writes

When it happens

Trigger: A write-capable spawn (non-isolated-worktree) on a manager constructed without a state_path while coordination_process_lock_required is set (require_coordination_process_lock wired by the host); embedding or test setups building an in-memory manager (state_path: None default) but enabling the shared-workspace lock; deployments where the state directory configuration was dropped.

Common situations: Custom embeddings of the Codewhale TUI manager without the app's state directory; test harnesses constructing managers with defaults that then exercise write-permission profiles; config regressions removing the state root while [subagents] write permissions remain enabled.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/931c41ff919b6e31. Report an issue: GitHub.