{error}; additionally failed to persist contention receipt:

Error message

{error}; additionally failed to persist contention receipt: {persist_error}

What it means

While durably registering a write-capable launch, persisting the write claim failed; the manager then tried to synchronously persist a contention receipt recording the refused launch, and that also failed. This is a compound error: the in-memory worker/coordination snapshot is restored (rolled back) and both the original error and the receipt-persist error are reported together. It signals the durable state store itself is unhealthy.

Source

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

                    let active_owners = self.active_coordination_owners();
                    self.coordination
                        .register_claim(claim, options.isolated_worktree, |owner| {
                            active_owners.contains(owner)
                        })
                })
                .transpose()
        } else {
            Ok(None)
        };
        let persisted_claim = match persisted_claim {
            Ok(claim) => claim,
            Err(error) => {
                if let Err(persist_error) = self.persist_state_synchronously() {
                    if let Some((worker_records, coordination)) = durable_launch_snapshot.as_ref() {
                        self.worker_records = worker_records.clone();
                        self.coordination = coordination.clone();
                    }
                    return Err(anyhow!(
                        "{error}; additionally failed to persist contention receipt: {persist_error}"
                    ));
                }
                return Err(anyhow!(error));
            }
        };
        let mut projection_capabilities = tools.clone().unwrap_or_else(|| {
            ["Bash", "File", "Git", "Run", "Web"]
                .into_iter()
                .map(str::to_string)
                .collect()
        });
        projection_capabilities.push(agent_type.as_str().to_string());
        if let Some(role) = assignment.role.as_ref()
            && !projection_capabilities.contains(role)
        {
            projection_capabilities.push(role.clone());
        }

View on GitHub (pinned to 0c42157ee5)

Solutions

Fix the underlying IO problem first: free disk space, correct permissions/ownership on the state path, remount read-write
Verify the state store is writable (a trivial write to the state directory) before retrying the launch
Retry the spawn only after the state store is healthy — never retry blindly, since each attempt may leave contention records half-written
If the state file is corrupted, restore from backup or remove it and let agents respawn (accepting the loss of prior coordination records)

Example fix

// before
let agent = manager.spawn_subagent_from_input(&request).await?;

// after
match manager.spawn_subagent_from_input(&request).await {
    Err(e) if e.to_string().contains("failed to persist contention receipt") => {
        alert_state_store_unhealthy(&e); // surface both errors; do not retry
        return Err(e);
    }
    other => other,
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight the state store before write-capable fan-out.
fn state_store_healthy(state_path: &Path) -> bool {
    let probe = state_path.join(".write-probe");
    std::fs::write(&probe, b"1").is_ok() && std::fs::remove_file(&probe).is_ok()
}

Try / catch

On the compound 'additionally failed to persist contention receipt' error, halt spawning immediately and page/alert on state-store health; the message carries both errors — log them as a pair and never auto-retry until the IO root cause is fixed.

Prevention

Monitor free space and writability of the coordination state directory as a first-class health signal
Keep the state file on a local filesystem with atomic rename support; avoid NFS for coordination state
Back up the coordination state file so corruption can be recovered without losing the whole session

When it happens

Trigger: Filesystem failures on the coordination state path during claim persistence — disk full, permission denied, read-only mount; a corrupted or locked state file that fails both the claim write and the synchronous persist; concurrent managers contending over a damaged shared state file.

Common situations: Disk-full incidents on long-running sessions; state directory ownership changed under a running process (container restart with different uid); NFS or exotic filesystems breaking atomic writes of the state file.

Related errors

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