[brettheap]

What was wrong

#85, and #72 item 6: a newline reached a one-line record. lanes-edit.sh's append_text_line appended its text with >> and only then proved the file had grown by one line. The append-line verb had no guard of its own, so a text carrying a newline was written whole and refused afterwards (exit 5, append changed line count by 2). write_event already refused a newline before writing (the R21 guard), so the object log was safe and the register was not.

lane-handoff puts its why into four places, and sanitize (which only replaced —) covers only the last two:

1. the handoff's top block,
2. the handoff commit's message,
3. the object log's PAUSED line,
4. the register's file-level PAUSED line.

To measure it, I ran the suite's own sandbox (a trimmed tests/test_lane_helpers.sh: setup plus the Amendment 17 section) against main f87fd5a with lane-handoff --lane repoHF-7 "$(printf 'clear\nsecond line')":

DBG rc=0
DBG commit: 844a494 LANES(repoHF-7@Eagle): state · PAUSED · swap; window testsess:0 @1; dir …; agent claude; ...
DBG commit: c477c93 LANES(pre-existing@Eagle): capture an uncommitted registry edit (row append)
DBG commit: c6151fa handoff(repoHF-7@Eagle): PAUSED, clear second line
DBG LANES.md tail:
DBG   | PAUSED — lane repoHF-7, session a17a0004-…@Eagle, 2026-10-13T18:35:18Z, clear
DBG   | second line kind unknown; handoff refreshed
DBG handoff head:
DBG   | ## RESUME PROMPT — PAUSED 2026-10-13T18:35:18Z (clear
DBG   | second line), agent claude, transcript a17a0004-…, kind unknown — …
DBG err: lane-handoff: the PAUSED line was NOT written — the helper's own refusal is above. …
DBG err: lane-handoff: the LANES.md file-level PAUSED line was not appended (the register may be busy or behind); …

So the act exited 0, and this is worse than the issue described:

• The handoff was committed with a top block split across two lines. A --- line in the why would also end the first prompt early, because that is where lane-start's handoff_top_block stops.
• The object log's PAUSED line was refused.
• append-line wrote two lines. The row flip right after it did not refuse the dirty register: its handle_preexisting committed those two lines as a peer's pre-existing edit.
• lane-handoff's own note then said the line "was not appended".

A carriage return was not refused anywhere on that path. wc -l does not count one, so append-line "LANDING — …\r…" was appended and committed with exit 0.

#72 item 5: the deferred lane-start command dropped --agent. Where no transcript uuid is knowable, lane-start prints the first act that will write the deferred records: $prog --no-launch $self_args. $self_args is only the lane. A codex launch never has a uuid here, so it always reaches that line, and the printed command dropped --agent codex. The person who ran it then had lane-agent choose the agent of the last PAUSED. For repoAG-4 in the suite that is claude. Measured at f87fd5a: lane-start: lane-start --no-launch repoAG 4.

One policy across #85 and item 6, and why

The writers refuse before they write, a typed why is refused at the door, and sanitize flattens as the second line of defence.

• Writers. append_text_line refuses \n and \r before its mktemp, so every caller has the gate. That covers append-line, add-row, log's Rule 6 line and the rename's lines; append-line proves its one line AFTER writing it, so a lane-handoff --why carrying a newline corrupts LANES.md and leaves the checkout dirty #85's own argument is one gate in the writer. The append-line verb also refuses before acquire_lock. The function's gate is reached only after handle_preexisting, which can commit a peer's register edit, and a refusal that has committed something is a refusal that wrote. This is where write_event already asks for log.
• lane-handoff's why is refused right after the arguments are read, before the identity triple, the refresh and every write. This is the only point that covers all four destinations: two of them never pass through sanitize, and the third (write_event) refused only after the handoff had been refreshed and committed, which is Ten hardenings Copilot rounds 4–6 raised on #47, filed rather than taken: the test lock's ownership, three signal/status gates, a deferred command that drops --agent, and the handoff skill catching up with its command #72 item 6's "handoff refreshed, record not written". It is also the rule this estate already keeps for every other free text that becomes one line: lane-end --reason, rename-lane's reason, and log's free text.
• sanitize now spells every line break ; : CRLF, a lone CR or a lone LF each becomes one ; . This is append-line proves its one line AFTER writing it, so a lane-handoff --why carrying a newline corrupts LANES.md and leaves the checkout dirty #85's first candidate and its "the caller spells the newline ; so that the act still happens". Nothing reaches it with a break today. It is kept so that a later caller cannot turn a break into a refused write in the middle of the act.

I chose refusing over flattening at the door because the person sees their own words refused with the reason and re-runs, and nothing is half-written. Silent flattening would also have worked; the trade is one re-run against the record differing from what was typed.

Note: lane-handoff has no --why flag. The why is the positional [why …], and the tests drive it that way.

What changed

• lanes-edit.sh
  • append_text_line refuses CR/LF before mktemp (exit 2, "Nothing was written").
  • The append-line arm refuses CR/LF before the lock (exit 2, "Nothing was written, and the lock was not taken").
• lane-handoff
  • A why carrying CR/LF is refused right after argument parsing (exit 2).
  • sanitize flattens CRLF, CR and LF to ; and still replaces —.
• lane-start
  • The deferred first-act command appends $(quoted --agent "$AGENT") where AGENT_EXPLICIT=1: an agent named on the command line, or a non-default one the record named.
  • It goes after the lane's own arguments, so --no-launch <repo> <n> stays contiguous.
  • I checked that this cannot change how the deferred run binds. For --agent claude, the deferred --no-launch in the live window still takes the resume-by-id branch for that window's own transcript, which comes before the AGENT_EXPLICIT new-session branch.

No doc quotes any message or flag I changed (checked docs/README-lanes.md, skills/*/SKILL.md, commands/*.md).

Functions and regions edited:

• lanes-edit.sh: append_text_line (new guard at the top of the function, ≈L1679-1696)
• lanes-edit.sh: main dispatcher, append-line) arm (new guard after the usage check, ≈L13561-13571)
• lane-handoff: top level, right after the argument-parsing loop (new block ≈L296-313; the why accumulation lines inside the loop are untouched)
• lane-handoff: sanitize (and its comment, ≈L2168-2186)
• lane-start: section 5b, the deferred-record note before if (( ! lane_sid_known )) (≈L3894-3910)
• tests/test_lane_helpers.sh: Amendment 17 section, after the repoHF-7 writer-validation block (≈L9474-9535)
• tests/test_lane_helpers.sh: section 4, lane-start --agent cases, after repoAG-1 and after repoAG-4 (≈L9960-9968, ≈L10027-10039)

Tests added, and fail-before / pass-after

In tests/test_lane_helpers.sh:

• Amendment 17 section, repoHF-7:
  • append-line with a newline is refused with exit 2. The register is byte-identical and git status --porcelain is unchanged.
  • The same for a carriage return.
  • append_text_line, lifted out of the helper the way the cut_to_line cases are, refuses a newline itself and leaves its file at its one line.
  • lane-handoff --lane repoHF-7 "$(printf 'clear\nsecond line')" is refused with exit 2. The handoff, the object log and the register are byte-identical, no commit is made, and the checkout is as it was.
  • The same refusal for a trailing CR.
  • sanitize, lifted into its own shell, turns a\r\nb\rc\nd — e into a; b; c; d; e.
• Section 4, --agent:
  • The codex launch of repoAG-1 defers a first act carrying --agent codex.
  • repoAG-4 (record agent claude, run --agent codex) defers exactly lane-start --no-launch repoAG 4 --agent codex.
  • A default-agent start with no uuid (repoAG-10, LANE_START_SESSION_ID=0) defers --no-launch repoAG 10 with no --agent.

Proof. I did not run the full suite locally (box load, and the AGENTS.md ruling of 2026-09-16). I ran one trimmed copy of the suite: setup lines 1-971, E/LOGD, write_record_a12, and the whole Amendment 17 section through section 4. I ran that same file against two exported trees, git archive f87fd5a and this branch's files, with every LANES_* seam unset and TMPDIR in a scratch directory:

pre  (f87fd5a): 180 passed, 18 failed   — 17 of the new assertions fail (rc 5/0 where 2 is expected, the register/handoff changed, HEAD moved, sanitize kept the breaks, the deferred line without --agent)
post (branch) : 197 passed, 1 failed

The one failure in both runs is …and a record written before Amendment 17 carries both EMPTY, which reads repoSW-1, a fixture from a section the trim leaves out. The new assertions that pass in both trees are expected to:

• …the object log not written: write_event already refused.
• …and the checkout as it was: before the fix the damage was committed, not left dirty.
• The repoAG-10 negative.

Also run locally:

• bash -n on all four files.
• python3 -m pytest tests/test_repo_hygiene.py (152 passed).
• CI's tests job is the suite of record for everything else.

Remaining, not in this PR

• append-line proves its one line AFTER writing it, so a lane-handoff --why carrying a newline corrupts LANES.md and leaves the checkout dirty #85's skill half. skills/handoff/SKILL.md step 4 (≈L347, "sanitize the operator's words once") should flatten CR/LF too. That file is being edited by lane 4's writer for skills/handoff/SKILL.md: the skill supplies the uuid (R-A11-5) but has no preemptive refusal for a lane that has never had a session recorded #98-skills/handoff/SKILL.md:39 hard-codes lanes-edit.sh's path; every sibling artifact (including skills/restart/SKILL.md) resolves it PATH-first #100 and by Handoff skill: commit the handoff in the checkout it was published in, by its own path, and refuse foreign staged entries and in-progress operations (#197) #199/Make every shell block in the handoff skill parse, and stop calling /rename the only act there is (#78, #79) #200, so it waits for lane 4's SKILL.md PR to land. The skill's append-line call (≈L552) already gets the new writer-side refusal.
• Ten hardenings Copilot rounds 4–6 raised on #47, filed rather than taken: the test lock's ownership, three signal/status gates, a deferred command that drops --agent, and the handoff skill catching up with its command #72 items 1-2 (tests/run.sh's lock ownership) are done: they landed on main in tests/run.sh refuses to start when it cannot record its lock's owner, and its cleanup removes only a lock that is still its own (#72 items 1-2) #232 as 19c2e25 on 2026-10-18, so they no longer wait for Follow up #190's test roots: name a refused root's value, check the pin's commit, find paired feature worktrees, show redirected roots under -q, run the lane manual sections, and restate the installer-source test #195.
• Ten hardenings Copilot rounds 4–6 raised on #47, filed rather than taken: the test lock's ownership, three signal/status gates, a deferred command that drops --agent, and the handoff skill catching up with its command #72 item 8 (the skill's exit-2 handling, SKILL.md ≈L85) waits for lane 4's SKILL.md PR.
• Ten hardenings Copilot rounds 4–6 raised on #47, filed rather than taken: the test lock's ownership, three signal/status gates, a deferred command that drops --agent, and the handoff skill catching up with its command #72 items 4 and 9 (a failed log PAUSED not stopping the register writes, in the command and in the skill) wait for Brett's ruling.
• Ten hardenings Copilot rounds 4–6 raised on #47, filed rather than taken: the test lock's ownership, three signal/status gates, a deferred command that drops --agent, and the handoff skill catching up with its command #72 items 3, 7 and 10 are already fixed or superseded at f87fd5a:
  • Item 3: lane-handoff's INT/TERM traps now exit 130/exit 143 (L1926-1927).
  • Item 7: the refresh goes through publish-handoff --expect-digest, not cat > file.
  • Item 10: /ctx is now lane-handoff --restart, SKILL.md ≈L684.

Part of #85
Part of #72

🤖 Generated with Claude Code

Summary by Sourcery

Prevent multiline lane records from being written and retain the intended agent when deferring lane-start records.

Bug Fixes:

• Reject carriage returns and newlines before writing one-line records, preventing partial lane-handoff updates and unintended register changes.
• Preserve an explicitly selected or recorded agent in deferred lane-start commands.

Enhancements:

• Flatten line breaks in lane-handoff sanitization as a secondary safeguard.

Tests:

• Add coverage for one-line writer refusals, atomic lane-handoff behavior, sanitization, and deferred agent preservation.

[sourcery-ai]

Reviewer's Guide

The PR closes newline and carriage-return paths that could write malformed one-line records or leave lane-handoff partially committed, by validating inputs before any write or lock and retaining defensive sanitization; it also fixes deferred lane-start commands to preserve an explicitly selected agent, with focused regression coverage.

Sequence diagram for pre-write newline rejection

sequenceDiagram
    participant Caller
    participant LaneHandoff as lane-handoff
    participant AppendLine as append-line
    participant Writer as append_text_line
    participant Register as Register

    Caller->>LaneHandoff: lane-handoff --lane lane why
    alt why contains CR or LF
        LaneHandoff-->>Caller: exit 2
        Note over LaneHandoff,Register: No refresh, lock, write, or commit
    else append-line text contains CR or LF
        Caller->>AppendLine: append-line text
        AppendLine-->>Caller: exit 2
        Note over AppendLine,Register: Lock is not taken
    else one-line text
        AppendLine->>Writer: append_text_line text
        Writer->>Register: append one line
    end

Loading

Sequence diagram for deferred lane-start agent preservation

sequenceDiagram
    participant User
    participant LaneStart as lane-start
    participant Deferred as Deferred lane-start

    User->>LaneStart: lane-start --agent codex lane
    alt transcript UUID unknown
        LaneStart->>Deferred: lane-start --no-launch lane --agent codex
        Deferred-->>User: First act preserves explicit agent
    else default agent with no explicit selection
        LaneStart->>Deferred: lane-start --no-launch lane
        Deferred-->>User: First act uses recorded/default agent
    end

Loading

Flow diagram for safe one-line record handling

flowchart LR
    Input[Input text] --> Validate{Contains CR or LF?}
    Validate -- Yes --> Refuse[Exit 2; nothing written]
    Validate -- No --> Sanitize[sanitize replaces line breaks with ; ]
    Sanitize --> Write[Write one-line record]

Loading

File-Level Changes

Change	Details	Files
Prevent embedded line breaks from corrupting one-line records or partially completing a lane handoff.	Reject CR/LF in the shared append helper before temporary-file creation or writing. Reject CR/LF in the append-line command before lock acquisition. Reject invalid lane-handoff why text immediately after argument parsing, before refreshes or commits. Retain sanitize as a defensive fallback that converts CR, LF, and CRLF to ; .	lanes-edit.sh lane-handoff tests/test_lane_helpers.sh
Preserve an explicitly selected agent in deferred lane-start commands.	Append a quoted --agent argument when the launch agent is explicit or differs from the default. Keep the lane arguments contiguous and avoid adding the flag when no explicit agent needs to be preserved. Add coverage for codex launches, record-agent mismatches, and default-agent starts.	lane-start tests/test_lane_helpers.sh
Add regression tests proving refusal is atomic and deferred commands retain agent selection.	Verify newline and carriage-return inputs leave handoff, log, register, git status, and HEAD unchanged. Verify the shared append helper independently rejects multiline input. Verify sanitize flattening and exact deferred command output.	tests/test_lane_helpers.sh

Possibly linked issues

• append-line proves its one line AFTER writing it, so a lane-handoff --why carrying a newline corrupts LANES.md and leaves the checkout dirty #85: The PR adds pre-write CR/LF rejection to append-line and lane-handoff, preventing the register corruption and dirty checkout described.

---

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 1 day and 9 hours by commenting @sourcery-ai review. Upgrade to get a review now.