Skip to content

Run several workers in one repository without them colliding

Give each worker a declared scope, and find out immediately when two of them claim the same paths.

described Parallel workersintermediateagentoperatorwrites state

Situation

Two agents work the same repository at the same time. Each is individually reasonable; together they edit the same file from different assumptions, and the conflict surfaces as a merge, long after the decision that caused it.

What you run

  • start: takes the paths this task may touch, and refuses a second active task in one checkout
  • check: --overlap reports other worktrees whose claims intersect yours
  • finish: refuses to accept work outside the claimed paths

Scenario

setup: two-worktrees
given:
  - 'a second worktree of the same repository with an active task scoped to lib'
steps:
  - id: claim-a-scope
    run: ['start', 'narrow the parser', '--scope', 'lib']
    note: 'the task starts, and the overlap with the other worktree is reported'
    expect:
      exit: 0
      stdout_contains: ['^started t-', 'overlap']
  - id: see-the-overlap
    run: ['check', '--overlap']
    note: 'scope containment against every other worktree, never blocking'
    expect:
      exit: 0
      stdout_contains: ['overlap']
  - id: nothing-to-refuse
    run: ['finish', '--check']
    note: 'no file outside the claimed scope has been touched'
    expect:
      exit: 0
      stdout_contains: ['0 failing']
then:
  - 'two workers on one repository see each other by scope, and the second is told before it starts'

Outcome

Overlap is reported when the task starts rather than when the branches merge, and a task record belonging to another checkout is reported as foreign rather than enforced against yours.

No scenario yet

This use case is described, not proved: it names its commands and rules, and nothing executes it. It cannot be more than described until a scenario is added.

Why the tool knows this

The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.

The rules that make it hold

Guarantees exercised

Related use cases

Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.

The moments this answers