exclusive-lock-dispatch

What this skill does

# Exclusive-Lock Dispatch

The dispatch-time pattern for tools that hold an exclusive lock during
execution. Running such a tool from multiple parallel agents is a guaranteed
failure; running the same tool's *outputs* through many parallel agents is
the right shape.

## When to Use This Skill

| Use this skill when… | Use `parallel-agent-dispatch` alone when… |
|----------------------|-------------------------------------------|
| Two or more candidate agents would invoke the same lock-holding tool | No candidate agent touches a locked resource |
| A prior wave emitted lock-contention errors | Agents only read pre-computed artefacts |
| You are debating "serialise the agent or pre-dump the artefacts?" | File scopes are disjoint and lock-free |
| The tool in question is slow (decompilation, migration, compile) so re-running per agent would burn minutes | The lock holder is cheap enough to serialise without pre-dump |

## Canonical Locked Resources

| Tool / Resource | Lock Behaviour | Typical Symptom |
|-----------------|---------------|-----------------|
| Ghidra project (`.gpr`) | Single writer; second invocation fails | `Project is locked by another instance` |
| Database migration lock | Single writer per database | Migration tool blocks or errors |
| Git index on shared checkout (`.git/index.lock`) | Single writer per working tree | `index.lock` exists / cannot `git add` |
| Taskwarrior bulk modify (`task modify`, `task done` ranges) | Effectively single-writer for the task store | Sporadic "task database is locked" or lost edits |
| Single-writer build caches (ccache, cargo target/, Bazel action cache) | First writer serialises others | Spurious build failures or cache corruption |
| Decompiler output caches | Re-analysis on every access | Minutes-per-agent rerun when artefacts could be shared |

## The Anti-Pattern

```
Wave plan:
  Agent A: ghidra -process BIN --script ExtractStrings.java
  Agent B: ghidra -process BIN --script ExtractXrefs.java
  Agent C: ghidra -process BIN --script ExtractStructs.java
  Dispatched in parallel.
```

Second invocation refuses to open the project. The orchestrator receives
two "failed" returns and, without this skill's discipline, dispatches
*more* agents to "retry" — multiplying the lock contention.

## The Pattern

### Step 1 — One serialised run emits every artefact

Run the locked tool exactly once (or once per distinct artefact kind),
writing everything downstream agents will need into **gitignored scratch**.
Keep the outputs under a stable path that the brief can reference:

```
tmp/decomp/strings.txt
tmp/decomp/xrefs.json
tmp/decomp/structs.json
tmp/ghidra/analysis.log
```

The pre-dump agent runs alone in its wave. Its return contract includes
the artefact paths as "produced" so downstream waves can cite them.

### Step 2 — Downstream agents read, do not re-analyse

Parallel agents in the next wave take the pre-computed artefacts as input
and produce their implementation slabs from those. No lock-holder
invocations, no re-analysis, no contention.

Briefs must reference artefacts by path:

> "Input artefacts: `tmp/decomp/strings.txt`, `tmp/decomp/xrefs.json`.
> Treat as read-only. Do not re-run Ghidra."

### Step 3 — Wave boundaries enforce exclusivity

The orchestrator never places two lock-contenders in the same wave.
`workflow-wave-dispatch` handles the scheduling; this skill is the
pre-work that makes wide parallelism possible afterwards.

## When to Pre-Dump vs Dispatch Directly

| Situation | Decision |
|-----------|----------|
| N ≥ 2 candidate agents would each need a fresh analysis of the same source | **Pre-dump**: one serialised run, then fan out |
| Exactly one agent needs the lock and no siblings do | **Dispatch directly**: the lone agent serialises itself |
| Lock holder is fast (< 10s) and agents need fresh state | **Dispatch serially**: skip pre-dump, run agents one at a time |
| Lock holder is slow and agents need only a stable snapshot | **Pre-dump**: amortises the cost across the fan-out |

The pre-dump cost is paid once. Serialising N agents pays the lock cost
N times and removes any parallelism benefit.

## Ghidra Specifics

Ghidra is the most common pre-dump target. The 12.x release changed
scripting:

| Concern | Current-as-of-2026 Answer |
|---------|---------------------------|
| Scripting language | `.java` post-scripts (Jython removed in 12.x) |
| First-time vs re-run | `-import` on first run; `-process` once the binary is in the project |
| Skip analyzers on re-run | `-noanalysis` |
| Headless wrapper | `analyzeHeadless <project_dir> <project_name>` |
| Output destination | Post-script writes to stdout or to a file under `tmp/` |

A typical pre-dump recipe:

```bash
# First run: import and analyse once
analyzeHeadless tmp/ghidra/ myproj -import path/to/bin \
  -postScript ExtractEverything.java tmp/decomp/

# Later runs: re-use analysis
analyzeHeadless tmp/ghidra/ myproj -process bin -noanalysis \
  -postScript RefreshStrings.java tmp/decomp/
```

## Taskwarrior Specifics

The `~/.task/` store is single-writer in practice. Dispatching five
agents to each `task modify` different filters produces sporadic
"database is locked" errors and, worse, silently lost edits when one
agent's write races another's.

The rule is the same: one orchestrator-owned agent (or the orchestrator
itself) performs the bulk mutation, derived tasks the parallel siblings
need are emitted to gitignored scratch (`tmp/tasks.json`), and the
parallel wave reads from scratch.

## Quick Reference

### Pre-Dispatch Checklist

- [ ] Identified every locked resource across candidate agents
- [ ] Confirmed which agents need lock access vs which just need artefacts
- [ ] Decided pre-dump vs serial dispatch using the table above
- [ ] Pre-dump artefacts targeted at a gitignored path under `tmp/`
- [ ] Downstream briefs reference artefact paths, not the lock holder
- [ ] Lock-holder agent runs alone in its wave

### Common Mistakes

| Mistake | Correct Approach |
|---------|-----------------|
| Dispatching N agents that each run the locked tool | Pre-dump once, fan out on artefacts |
| Retrying the locked agent on failure | Diagnose the lock, then either serialise or pre-dump |
| Committing `tmp/decomp/` or `tmp/ghidra/` | `.gitignore` the scratch directory |
| Briefing "and run Ghidra again to double-check" | Once the artefacts exist, treat them as authoritative |

## Related

- `parallel-agent-dispatch` — overall dispatch contract; §Wave Splits cites this skill
- `workflow-wave-dispatch` — wave scheduling between lock-holder and parallel waves
- `.claude/rules/parallel-safe-queries.md` — commands that exit 1 on empty, a different form of parallel foot-gun

> Evidence: six-wave renderer landing shipped with zero lock-contention
> retries after adopting pre-dump for the decompiler and the task queue.
> Before this discipline, ad-hoc parallel dispatches frequently consumed
> an entire wave recovering from lock errors.