[brettheap]

A follow-up to #246 (T018 of feature 004, the triad lane tooling) that must land before the triad cutover (#186). It fixes the two sections of #255.

The handoff names every inventory record that is not a whole schema-1 one, and a leg directory this account cannot search is unreadable, never absent. Both gaps broke #246's own rule, Amendment 7(d): a read that failed is never an empty one.

These readers run only in an assembly, a checkout whose project.yaml declares a leg, so main is not exposed before the cutover.

What it fixes

• Section 1, the handoff's tree inventory (lane-handoff, paired_inv and pi_bad):
  • Before: a lane-trees row counted as unreadable only where its path was empty. A record of another schema keeps its path, so it read as a record with an empty checkout, and the paired tree it names was polled as this lane's writer, with no NOT POLLED note.
  • Now: the row's schema, field 13, decides. A row whose schema is not 1 is named in the NOT POLLED note by its id, its schema and any path it keeps, the lane stays SWAPPING, and the row never reaches paired_inv. The lane-trees row format is untouched.
• Section 2, a leg directory with no search permission:
  • Before: its .git could not be tested, and each reader's .git test failed there exactly as for a leg that is not checked out. The sweep listed it absent and exited 0. lane-reconcile gave no TREE row. The handoff said nothing and re-recorded the leg's tree under the assembly. lane-end ENDED the lane over the lane's unpushed commit in the leg.
  • Now, in one set of words ("its directory cannot be searched, so whether it has a .git of its own could not be tested, and git could not read it: <git's first line>"):
    • lane-worktrees' probe_leg asks lstat for <leg>/.git. Only ENOENT or ENOTDIR is a leg with no .git, and any other failure sets read_error, so the leg counts unreadable: the sweep's exit 3, lane-end's refusal, and the report's legs section.
    • lane-handoff and lanes-edit.sh's lane_reconcile take their unreadable-leg branch where the .git test fails and the leg directory fails -x. The handoff gets an UNREADABLE LEG line, a count and a withheld tree. The reconciliation gets a TREE row unreadable that requires recovery.
    • A leg directory that is not there at all is still absent.

What the fold-in adds. Lane 3's independent review found the same failure in a reader the issue does not name. After the cutover, code/upstream/openRepoShape is exactly this kind of dependency.

• A dependency nested in an unsearchable directory (aae85a2, the review's finding 1):
  • Before: git lists a dependency nested in a leg as - (not initialized) and exits 0, not only where it was never initialized but also where it cannot search the directory: at mode 000, at read-without-search, or under a directory it cannot search. assembly_checkouts skipped every - line before it probed anything, so such a dependency got no row, the code leg read clean, the sweep exited 0, and lane-end ended the lane over the lane's unpushed commit in it.
  • Now: a - line is parsed as an initialized one is, and probed (probe_uninitialized). It becomes a row only where the read failed, an unreadable row, counted, in the words probe_leg already gives. A directory that is not there, or one that is empty and can be searched, is a dependency never initialized and still adds none.
• A dependency cloned by hand (a16e534, i): a clone made into the directory of a deinitialized dependency is still listed -, so the sweep skipped it and lane-end ended the lane over the lane's unpushed commit in it (measured). It is now read like an initialized dependency: a row, unpushed there, counted, exit 3.
• The describe-suffix trim (a16e534, ii): git prints a describe suffix only on a or + line, never on a - line. A dependency never initialized at upstream/dep (1) was read as upstream/dep, which made a second row for the initialized dependency beside it and left dep (1) unread. The trim now applies to the initialized branch only.
• The review's two test gaps (c67f7a6):
  • MS6: the unknown-schema test now runs for schemas 2 and 10, so a rule that matched the schema by its first character reads 10 as a schema-1 record and fails.
  • MS5: a record that files a tree id and no path is named in the NOT POLLED note by its id and schema, its tree is no writer of the lane's, and nothing is filed over it. A record this account cannot read (<unreadable>, no path) is named the same way.
• The docs (c67f7a6, a16e534): docs/README-lanes.md says what the sweep does with a dependency git lists as not initialized, and The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255's own added text is reflowed where its insertion left ragged lines.

The branch. fix/255-unreadable-inventory-and-leg-pr is a16e534 on main 55aae16: 7 files, 674 insertions and 30 deletions.

• Lane openRepoTools-2's two commits, cherry-picked:
  • 13397aa (from ba13d21): the two fixes, in lane-handoff, lane-worktrees and lanes-edit.sh, with four tests;
  • e678c61 (from 523b381): docs/README-lanes.md's T018 section, docs/triad-lane-tooling-analysis.md section 7 item 11 naming park.sh's WIP commit carries a Lane: <lane> trailer, and resume.sh records each tree it rebuilds under its leg, so openRepoTools' sweep and lane-end count a parked or resumed paired tree as its lane's (opensoft/openRepoTools#186, T018 §7 item 11) openBenches#166, and lane-handoff's T018 section heading, now 3b.
• Lane 3's three fold-in commits: aae85a2, c67f7a6 and a16e534.
• Why a cherry-pick: Make the lane tools look inside a triad's legs and paired feature trees, so the sweep, lane-end's gate, lane-handoff, lane-reconcile and the daily report can see a lane's work there, and change nothing a checkout with no project.yaml does #246 landed as the squash 55aae16, so a merge of main into lane 2's branch conflicts in all seven files. The PR is the two commits cherry-picked onto main, with no force-push anywhere. Their diff equals git diff 5dd0df0 523b381 (the same patch-id), and their tree at e678c61 is 1a46c72, the tree the reviewer computed.

Tests. There are 11 test_255_ functions: lane 2's four, and the fold-in's seven. Under Runs, six of the seven fail under a mutant of the code they hold. The seventh, the unreadable record, needs no #252.

• Lane 2's four, each failing on 5dd0df0's tools and passing here:
  • tests/test_triad_lane_tooling.py: test_255_a_leg_directory_that_cannot_be_searched_is_unreadable_and_holds_lane_end;
  • tests/test_triad_lane_tooling_handoff.py: test_255_a_leg_directory_that_cannot_be_searched_is_unreadable_in_the_handoff_and_reconcile, test_255_an_unknown_schema_record_is_named_in_the_handoffs_not_polled_note and test_255_a_malformed_record_is_named_in_the_handoffs_not_polled_note. The <malformed> row comes from a fake lanes-edit.sh, so this test does not wait for Lifecycle reads that failed are no longer answers, set-lane-tree's fence closes with its operation, and a lane sidecar is valid only when whole #252.
• The fold-in's seven:
  • tests/test_triad_lane_tooling.py: a nested dependency's directory at mode 000 and at 0600, and beneath a directory that cannot be searched, each holding the sweep and lane-end; a dependency never initialized, which adds no row; a dependency cloned by hand, read as unpushed; and a dependency at upstream/dep (1), read by that path;
  • tests/test_triad_lane_tooling_handoff.py: the tree id with no path, and the unreadable record.
• Where they live: the issue asked for them beside T018's cases in tests/test_lane_helpers.sh. T018's fixtures live in the two Python modules, so the tests are there (the review's ruling).

The order with #252 (the review's NIT 5). <malformed> is #252's row, so the handoff names a truncated record only where lane 4's #252 is on main. The review asked for #252 first, and that is what happened: #252 merged as 00d52ae at 2026-10-19T18:14Z, and q6b is built on it. With this PR on today's main, <malformed> records are named (the review measured it with #252 and #255 together, under Review).

Follow-ups, not in this PR:

• a declared leg under an unsearchable parent (the review's ruling on lane 2's doubt: a follow-up);
• a leg at mode 0100, searchable and not listable, which reads clean (finding 4, estate-wide; lane 3 proposes it to Brett Heap for v1.2.0, The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255 6272494888);
• the top block's contradiction for a paired tree that only a broken record names (finding 3; proposed for v1.2.0 in the same comment);
• the handoff's wording on Lifecycle reads that failed are no longer answers, set-lane-tree's fence closes with its operation, and a lane sidecar is valid only when whole #252's refusal code (NIT 8; lane 3 proposes it as a v1.2.0 item, The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255 6272494888).

Runs

• The record, q6b (55aa3db, branch lane3-queue/q6b-255-on-q5b: q5b dd2b9f0 + this head a16e534, on main 00d52ae, tree f5aa12a): tests.yml run 39302719561, pending. This is the run of record for the landing.
• An early read, q3a (dce6ffb, branch lane3-queue/q3a-255-on-q2f: PR 2's prefix q2f, aeadabe, + lane 2's two commits alone, at e678c61; tree 47413c4; on main 55aae16): run 39289273676, green on every job, the shell suite included.
• The fold-in writer's selection at a16e534: -k "test_255 or triad or lane_worktrees or repo_hygiene" gave 421 passed (logs in briefs/ort3-255-should1-work/ in lane 3's tree).
• The fold-in's mutants: the writer ran seven and each fails a test_255_ test.
  • The finding-1 fix reverted (FX0), and two variants of it: every - line a row (FX1), and a - line asked of probe_leg alone (FX2).
  • The two later rulings reverted one at a time: the hand-cloned case (RV1) and the describe-suffix trim (RV2).
  • The reviewer's MS5 and MS6.

Review. Lane 3's independent reviewer gave LAND on 523b381 (briefs/rv-255-final-20261019.md in lane 3's tree, posted on #255 as 6272494888). Both fixes do what sections 1 and 2 ask, in every reader named.

• What it ran:
  • the four new tests fail on 5dd0df0 for the right reason and pass on 523b381;
  • 17 of 19 mutants are killed, and the two survivors, MS5 and MS6, are low-impact (the fold-in's tests now kill both);
  • with Lifecycle reads that failed are no longer answers, set-lane-tree's fence closes with its operation, and a lane sidecar is valid only when whole #252 (3ffefce) the fix merges cleanly, and against the real lanes-edit.sh the handoff names the <malformed> record, in 5 of 5 cases. On that tree, main + Lifecycle reads that failed are no longer answers, set-lane-tree's fence closes with its operation, and a lane sidecar is valid only when whole #252 + The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255, the selection -k 'test_255 or triad or lifecycle_fail_open or repo_hygiene or lane_worktrees' gave 457 passed;
  • the shell suite on that tree gave 4889 passed and 2 failed, test_lane_helpers.sh:1269 and :8548, both in lane-start's row stamp. The reviewer takes them as its sandbox's 106-character path reaching the 240-character ROW_STATE_CAP, and neither The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255 nor Lifecycle reads that failed are no longer answers, set-lane-tree's fence closes with its operation, and a lane sidecar is valid only when whole #252 touches lane-start or the cap. q3a is green on every job, the shell suite included.
• What lane 3 did with the findings:
  • finding 1, a SHOULD, and NITs 6 and 7: folded in, above;
  • finding 2, a SHOULD: the cherry-pick, above;
  • findings 3 and 4, and NIT 8: the follow-ups, above;
  • NIT 5: the order with Lifecycle reads that failed are no longer answers, set-lane-tree's fence closes with its operation, and a lane sidecar is valid only when whole #252, above.
• The reviewer's re-check of e678c61..a16e534 is pending.

Landing: Brett Heap's decision 4 on #228 ("Yes, merge when green (Recommended)"), and his word of 2026-10-18T20:3xZ, "use this as approval to merge when green for all merges thru v1.1.0".

• Lane openRepoTools-3 lands the queue in one order: openRepoTools becomes the openrepotools package: pipx installs the wheel with the whole payload, --install leaves pipx's link to pipx, --version names the release, and every count line says where the other commands come from (#228, PR 1 of 4) #262, PR 2, PR 3, PR 4, T025's docs PR, then The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255.
• This PR squash-merges after an independent review, once Linux CI is green on the exact tree main will have after its squash. The record is a queue run of tests.yml on lane 3's prefix branch, under Runs.
• The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255 is last in the queue. q6b is q5b plus this head, so PRs 2 to 4 and T025 are beneath it.
• When its turn comes, lane 3 pushes a head that merges main into a16e534 with q6b's tree, as a fast-forward, so the tree under review is the tree that was tested.

Lane: openRepoTools-3

🤖 Generated with Claude Code

Summary by Sourcery

Prevent failed reads from being treated as empty state during lane sweeps and handoffs, preserving safety for unreadable legs, dependencies, and inventory records.

Bug Fixes:

• Treat leg directories and nested dependencies that cannot be searched or read as unreadable rather than absent or clean, preventing unsafe lane completion and handoff updates.
• Identify every inventory record that is not a complete schema-1 record in handoff output and exclude its associated tree from polling.
• Handle manually cloned and path-suffixed uninitialized dependencies correctly while continuing to ignore genuinely empty or missing dependencies.

Enhancements:

• Expand lane documentation to describe unreadable legs, dependency handling, and non-schema-1 inventory records.

Documentation:

• Document the updated sweep, handoff, reconciliation, and dependency behavior for unreadable paths and malformed inventory records.

Tests:

• Add coverage for unreadable legs and nested dependencies, manually cloned dependencies, unusual dependency paths, and malformed or unreadable inventory records.

[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 by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

The PR closes #255 by making permission and inventory-read failures explicit and fail-safe across all lane readers, while distinguishing genuinely absent or uninitialized paths from unreadable checkouts and adding focused regression tests and documentation.

Sequence diagram for unreadable dependency handling

sequenceDiagram
    participant Sweep as lane-worktrees
    participant Git as git
    participant Probe as probe_uninitialized
    participant LaneEnd as lane-end
    Sweep->>Git: list dependencies
    Git-->>Sweep: dependency status line
    alt dependency line is -
        Sweep->>Probe: probe_uninitialized
        Probe->>Git: read dependency path
        Git-->>Probe: read failure
        Probe-->>Sweep: unreadable
        Sweep-->>LaneEnd: exit 3
        LaneEnd->>LaneEnd: refuse lane end
    else dependency is missing or empty and searchable
        Sweep-->>LaneEnd: no dependency row
    else dependency contains a readable hand clone
        Sweep-->>LaneEnd: unpushed row
    end

Loading

Flow diagram for unreadable leg classification

flowchart TD
    A[probe_leg] --> B{Leg directory exists?}
    B -->|No| C[absent]
    B -->|Yes| D{Can lstat leg/.git?}
    D -->|ENOENT or ENOTDIR| E[No .git: continue normal probing]
    D -->|Other failure| F[read_error]
    D -->|Readable| E
    E --> G{Can search leg directory?}
    G -->|No| F
    G -->|Yes| H[Read leg state]
    F --> I[unreadable]
    I --> J[lane-worktrees exit 3]
    I --> K[lane-end refuses]
    I --> L[lane_reconcile emits TREE unreadable]
    I --> M[lane-handoff emits UNREADABLE LEG]

Loading

Flow diagram for non-schema-1 inventory records

flowchart TD
    A[lane-trees] --> B[Read record schema field 13]
    B --> C{Schema is exactly 1?}
    C -->|No| D[Name record in NOT POLLED note]
    D --> E[Include id, schema, and retained path]
    D --> F[Keep lane SWAPPING]
    D --> G[Do not pass record to paired_inv]
    G --> H[Do not poll its paired tree as this lane's writer]
    C -->|Yes| I[Pass record to paired_inv]
    I --> J[Normal paired-tree inventory handling]

Loading

File-Level Changes

Change	Details	Files
Classify unreadable legs and nested dependencies as unreadable rather than absent or clean, and propagate that status through sweep, reconciliation, handoff, reporting, and lane-end safety gates.	Probe .git with distinct handling for missing paths versus permission or read failures. Inspect - submodule entries so inaccessible directories and hand-cloned repositories are reported, while genuinely uninitialized dependencies remain absent. Preserve and report the shared unreadable-leg wording, recovery requirements, counts, and refusal to end affected lanes. Document the updated leg and dependency semantics.	lane-worktrees lanes-edit.sh docs/README-lanes.md
Make lane handoff inventory parsing reject every record that is not a complete schema-1 record, preventing unknown, malformed, pathless, or unreadable records from being polled as writers.	Use the complete schema field to classify inventory rows, including schemas 2 and 10 without prefix matching. Name each rejected record by id, schema, and retained path where applicable in the NOT POLLED note. Keep the lane SWAPPING, avoid overwriting records, and exclude trees named only by rejected records from this lane’s writers. Add coverage for malformed, unknown-schema, pathless, and unreadable inventory records.	lane-handoff tests/test_triad_lane_tooling_handoff.py
Add regression coverage for permission failures, dependency discovery edge cases, and handoff/reconciliation behavior.	Test unreadable declared legs and nested dependencies at multiple permission modes, including inaccessible parents. Verify absent and empty searchable dependencies remain uninitialized and uncounted. Verify hand-cloned dependencies are scanned and classified as unpushed. Preserve dependency paths containing parenthesized suffixes and validate lane-end refusal and exit statuses.	tests/test_triad_lane_tooling.py tests/test_triad_lane_tooling_handoff.py
Record the associated tooling analysis and user-facing behavior changes.	Link the completed workBenches issue in the triad analysis. Describe unreadable and not-initialized dependency semantics and handoff safeguards in the lane documentation.	docs/triad-lane-tooling-analysis.md docs/README-lanes.md

Possibly linked issues

• The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255: The PR implements both requested fixes: flags non-schema-1 inventory rows as unreadable and handles unsearchable leg directories as unreadable across readers.

---

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.

[brettheap]

Lane openRepoTools-3, 2026-10-19T21:0xZ: the independent re-check of #271's fold-in round, e678c61..a16e534, is LAND. There is no MUST and no SHOULD, and four NITs, all left for v1.2.0.

Finding 1's failure is gone. In every case the setup is this lane's unpushed commit in code/upstream/dep. The probes ran with the real tools, on main 00d52ae + a16e534 and on a16e534 alone:

Case	Result
the dependency's directory at mode 000 or 0600	unreadable retire, the sweep exits 3, lane-end exits 2 "NOT ended" (at e678c61: exit 0, and it ENDED)
code/upstream at 000 or 0600	git still prints - and exits 0. The row is unreadable ("a directory above it cannot be searched…"), the sweep exits 3, lane-end exits 2
a hand clone on a - line	unpushed retire on branch in-dep, the sweep exits 3, lane-end exits 2

Nothing else changes behaviour:

• lane-handoff, lanes-edit.sh and probe_leg are untouched in this range.
• An initialized dependency keeps its (…) trim and its one row.
• A never-initialized dependency, missing or empty and searchable, still gets no row.
• With Lifecycle reads that failed are no longer answers, set-lane-tree's fence closes with its operation, and a lane sidecar is valid only when whole #252 (00d52ae): a truncated, a misfiled and an unreadable record are each named in the NOT POLLED note. In each case the lane stays SWAPPING, the tree is not polled, and the record stays byte-identical.
• The selection on 00d52ae + a16e534: -k 'test_255 or triad or repo_hygiene or lane_worktrees or lanes_index' gave 547 passed.
• The merge: 00d52ae + a16e534 merges cleanly, and the result is The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255's diff alone. The handoff skill's two PAUSED writes carry the why it computed, sanitized as lane-handoff's sanitize does, and a why carrying a line break is refused before step 1 (#80 item 7, #85) #264 and Re-cut T006's assembly-0001 and regenerate T010's code-leg tests.yml patch against the files #228's series leaves, add T009's assembly-root length-caps patch, and mark lines 17 and 33 of the Gate B walk PARTLY until they are reviewed (part of #186) #266 share no file with The handoff names every inventory record that is not a whole schema-1 one, and a leg directory this account cannot search, or a dependency nested in one, is unreadable and never absent (fixes #255) #271.

The mutants:

• 8 of the 9 new ones are killed: the - skip restored, probe_leg without the stat, the hand-clone condition dropped, the trim applied to - lines, the stat's failure swallowed, every - line given a row, and "no such file" read as a failure.
• MS6 is killed.
• N8 survives: new wording for the stat branch.
• MS5 survives on 00d52ae: under Lifecycle reads that failed are no longer answers, set-lane-tree's fence closes with its operation, and a lane sidecar is valid only when whole #252 a record with no path is <malformed>, so that arm is now defence in depth.

The NITs, all going to v1.2.0:

1. NIT 8 is confirmed on 00d52ae, and it is old code.
   • What happens: over a malformed own-root record, set-lane-tree refuses with exit 1 and says "its sidecar … is not a record this helper can read" (lanes-edit.sh:18313). lane-handoff:2123 drops that message and prints the exit-7 fence wording.
   • Weight: it fails safe.
2. N8's wording is untested (tests/test_triad_lane_tooling.py:777).
3. The parent test accepts exit 2 or exit 3 (:772). On a git that fails git submodule status under an unsearchable parent, two mutants would survive. Git 2.43 prints - here, so the test bites on Eagle.
4. MS5 is equivalent on the landing tree.

The landing: #271 lands last in lane 3's queue, on prefix q6c (f4af690, tree ca46e88, run 39322404772). That is the main #264 and #266 leave, plus #228's series.

Lane: openRepoTools-3

[sonarqubecloud]

Quality Gate passed

Issues
22 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