[brettheap]

What was wrong

Issue #30's dead-lane exception (PR #61) lets a TAKEOVER displace an earlier TAKEOVER: A claims, B takes over from A, and C takes over from B once B is dead. superseded_by, and its inline copy in lane_objects, asked only "does some other lane's last line here read TAKEOVER". So B's stale TAKEOVER was read as proof that C was displaced too.

Evidence: I ran lanes-edit.sh at f87fd5a against a throwaway workspace (LANES_NO_GIT=1, LANES_NO_GITHUB=1, a temp HOME). The logs were the issue's shape: repoZ-5 dead with TAKEOVER … ← lane:repoZ-0, then repoZ-6 with TAKEOVER … ← lane:repoZ-5.

who opensoft/repoZ#40              HOLDS=0
  super.   lane repoZ-5  TAKEOVER … superseded by TAKEOVER (lane:repoZ-6)
  super.   lane repoZ-6  TAKEOVER … superseded by TAKEOVER (lane:repoZ-5)
  state    FREE — no lane's last line on it is open
who --lane repoZ-6
  TAKEOVER  opensoft/repoZ#40 … ← lane:repoZ-5  (taken over by lane:repoZ-5 … — release it to close this line)

The same bug has three consequences at f87fd5a, each reproduced by the suite's new fixtures:

• claim grants a plain CLAIMED over a held object. On a chain whose last link is dead, claim --force found no holder and wrote CLAIMED — lane repoChain-4 … opensoft/repoChain#1, not a takeover. Rule 1 exists to prevent exactly this outcome.
• who --lane and lane-end misdirect the true holder. They told the true holder it had been "taken over" by the lane it took the object from, and handed it the release that would free the object.
• The documented race is wrong. Two takers of one stale claim, neither naming the other, also displaced each other. who called the object FREE, while docs/README-lanes.md ("Known, deliberate") has always said both are holders. That text dates from The --help sentence naming what --install places beside this file reads like it's missing a word #3; the gate that made a TAKEOVER displaceable came with claim --force takes over a dead lane's hold; lane-end --retire ends a duplicate holder #61.

What changed

Every link that displaces a TAKEOVER names the lane it displaced as ← lane:<x>. claim --force writes that payload for every hold that is not a CLAIMED, and a comment URL is only ever the payload for a CLAIMED taken over. The rule now depends on the lane's own last line:

• That line is a TAKEOVER. It is displaced only by another lane's standing TAKEOVER that names this lane, and not by one this lane's own TAKEOVER names back. So B is displaced by C and C by nothing: one lane holds the object, the chain's last link.
• That line is any other open verb. It is displaced by any standing TAKEOVER, as before. The taker named is one no other standing TAKEOVER names, i.e. the lane that holds the object now, so A's line says C, not B.
• Two takers neither naming the other are both holders, which matches the README again.
• Two TAKEOVERs naming each other are both holders as well. No file order says which came last, so the conflict is shown instead of reported as FREE.

lane_objects applies the same rule, so who --lane and lane-end agree with who. The stale-CLAIMED path that pays a comment URL needs nothing: a URL only ever displaces a CLAIMED, never a TAKEOVER, so it is never a link a chain is followed by. R18 is unchanged: a taker that has released no longer displaces anyone. The single-hop shapes the suite already covers give the same answers as before.

Functions and regions edited:

• lanes-edit.sh: lane_objects (other-lane block and END, lines 3422-3466)
• lanes-edit.sh: superseded_by (its header comment and awk, lines 3495-3557)
• tests/test_lane_helpers.sh: seed rows (repoChain-1..4, after repoL-6's row)
• tests/test_lane_helpers.sh: seeded object logs (repoChain-1/2/3, after repoL-5's log)
• tests/test_lane_helpers.sh: the #30 dead-lane takeover block (repoL-6's pinned assertions, and the new repoChain cases after it)
• docs/README-lanes.md: "State is per lane" (the superseded_by reports zero holders for a chain of two dead-lane TAKEOVERs on one object #74 paragraph replaced by the rule, and "Known, deliberate")
• docs/README-lanes.md: the index schema table, holds (a VIEW) row

Tests

• repoL-6's pinned assertions are flipped. The block that pinned ZERO holders as the known superseded_by reports zero holders for a chain of two dead-lane TAKEOVERs on one object #74 gap now expects exactly one HOLDS, repoL-6, with repoL-5 superseded by repoL-6. It also checks that who --lane repoL-6 does not say "taken over by".
• Three-link chain, made through the tool. repoChain-1 claims #1, repoChain-2 takes it over from repoChain-1, and repoChain-3 from repoChain-2, all seeded and dead. Then LANES_LANE=repoChain-4 claim opensoft/repoChain#1 --no-github --force must write TAKEOVER … ← lane:repoChain-3. who must report exactly one HOLDS, repoChain-4, and each earlier link must be superseded by the link that names it.
• The race. On #2, two TAKEOVERs name repoChain-1. Expected: two HOLDS, state HELD, and claim --force refused with exit 2 ("is held by 2 lanes"), writing nothing.
• Mutual naming. On #3, two TAKEOVERs name each other. Expected: two HOLDS.

Local proof that they fail before and pass after. I did not run the full suite locally, per AGENTS.md; CI's tests job is the record. I ran a scratch mini-suite instead. It extracts the suite's own text by line range: the helpers ok/bad/is/has/hasnt/run, the new seed rows, the seeded logs, and the whole block from repoL-6's claim to the last new assertion. It runs that text in a temp workspace under env -i with LANES_NO_GIT=1 LANES_NO_GITHUB=1:

f87fd5a lanes-edit.sh:  10 passed, 15 failed
this branch:            25 passed, 0 failed

A separate scratch harness drove who and who --lane on nine shapes. Holder counts, before → after:

shape	before	after
chain of 2	0	1
chain of 3	0	1
chain of 2 with a case-folded payload	0	1
R18 chain whose last link released	1	1
single hop	1	1
race	0	2
a TAKEOVER naming its own lane	0	2
mutual naming	0	2
real claim --force over a dead TAKEOVER	0	1

bash -n passes on both shell files.

Known remainders (not fixed here)

• The lanes-index holds view still applies the one-hop rule. Evaluating ddl("sqlite", "") from lanes-index on an in-memory store returns no row for the two-link chain and none for the race, where who now names the last link and both racers. Fixing it means changing the view's SQL to read ref/payload. Existing SQLite stores also need a DROP VIEW first, because CREATE VIEW IF NOT EXISTS keeps the old definition. That is a separate change to the indexer. The README's holds row now says so, and test_the_holds_view_answers_as_who_does (single-hop) is unaffected.
• A lane renamed between links (Amendment 16(e)) keeps its old name in the next link's ← lane:<old> payload. That chain shows two holders (a visible conflict) and does not resolve.
• A ring of three or more TAKEOVERs each naming the next still displaces all of them. Only the two-lane mutual case is handled.

Closes #74

🤖 Generated with Claude Code

Summary by Sourcery

Make takeover resolution follow explicit lane links to the final holder while retaining ambiguous takeover conflicts as visible multi-holder states.

Bug Fixes:

• Resolve takeover chains to their final link so holder detection, forced claims, and lane-specific guidance identify the actual current holder.
• Preserve visible conflicts for competing takeovers that do not establish a clear displacement relationship.

Enhancements:

• Apply consistent takeover-chain semantics across who, who --lane, and lane-end through the shared object-resolution logic.
• Document the updated takeover displacement rules and clarify that the indexed holds view still uses the previous one-hop behavior.

Documentation:

• Update lane state documentation to describe final-link takeover resolution, conflict cases, and the remaining holds view limitation.

Tests:

• Add coverage for multi-link takeover chains, competing takers, mutual takeover naming, forced claims, and holder-specific output.

[sourcery-ai]

Reviewer's Guide

This PR fixes takeover-chain state derivation by making superseded_by and lane_objects follow explicit ← lane:<x> links, ensuring the last takeover is the sole holder while preserving visible conflicts for ambiguous races; it adds focused fixtures and updates documentation, while explicitly leaving the SQLite holds view unchanged.

Sequence diagram for force-claim takeover-chain resolution

sequenceDiagram
    actor User
    participant Claim as claim --force
    participant Logs as Lane logs
    participant Who as who

    User->>Claim: claim object
    Claim->>Logs: read each lane's last line
    Claim->>Logs: write TAKEOVER ← lane:repoChain-3
    User->>Who: inspect object
    Who->>Logs: follow TAKEOVER links
    Logs-->>Who: repoChain-4 is the sole holder
    Who-->>User: HELD by repoChain-4

Loading

Flow diagram for takeover-chain holder resolution

flowchart LR
    A["A: CLAIMED"] -->|TAKEOVER ← lane:A| B["B: TAKEOVER"]
    B -->|TAKEOVER ← lane:B| C["C: TAKEOVER"]
    B -. superseded by named link .-> X["B is displaced"]
    C --> H["C is the sole holder"]
    A -. stale earlier line .-> S["A and B are superseded"]

Loading

Flow diagram for ambiguous takeover conflicts

flowchart LR
    R["Stale claim"] --> A["TAKEOVER ← lane:A"]
    R --> B["TAKEOVER ← lane:A"]
    A --> H1["A is a holder"]
    B --> H2["B is a holder"]
    H1 --> C["who reports HELD by 2 lanes"]
    H2 --> C

Loading

File-Level Changes

Change	Details	Files
Make takeover supersession follow explicit lane-to-lane links so chains resolve to their final holder.	Record ← lane:<x> payloads for takeover links and distinguish them from comment URLs. Update superseded_by to displace a takeover only when a standing takeover names that lane; preserve ordinary open-verb behavior and represent races as conflicts. Apply the same chain-aware logic in lane_objects so who, who --lane, and lane-end agree. Ensure claim --force creates a takeover naming the current last link rather than a plain claim over a held chain.	lanes-edit.sh
Expand regression coverage for takeover chains and ambiguous takeover conflicts.	Add dead-lane fixtures for a three-link chain, two independent takers, and mutually naming takers. Verify the final chain link is the sole holder, earlier links are superseded by the links naming them, and who --lane does not misdirect the holder. Verify races remain held by two lanes and claim --force refuses without writing.	tests/test_lane_helpers.sh
Document the revised takeover resolution rules and identify the remaining index-view discrepancy.	Describe chain resolution, naming requirements, and conflict cases in the lane-state documentation. Clarify that the SQLite holds view still uses the old one-hop rule and is outside this change.	docs/README-lanes.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#74	Make who report the final lane in a chain of TAKEOVERs as the sole holder, rather than treating an already-superseded TAKEOVER as evidence that the final lane is also superseded.	✅

Possibly linked issues

• superseded_by reports zero holders for a chain of two dead-lane TAKEOVERs on one object #74: The PR fixes the reported superseded_by chain bug, updates lane_objects, and adds regression tests for chains.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days and 4 hours by commenting @sourcery-ai review. Upgrade to get a review now.