laurigates/exclusive-lock-dispatch

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:

# 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.