[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #1056 (comment)

Goal

Where a git that git's update ran dies of a signal, make bootstrap in a family holder now fails naming it wherever the update met it, not only where the signal's code is the update's last. This is #1056, found by rv996, lane 5's independent review of #1045 (issuecomment-6288783192, checklist candidate 1).

Git keeps only the last code that is not 0 (update_submodules in git 2.47.1's builtin/submodule--helper.c), and only 128 stops it. So a member's crash or kill before a later gitlink's 128 or 1 left no signal in the update's exit code, and #1045's ended_on saw none: the run said the credential advice and family bootstrap ok, exit 0, with IRRS's legs never updated.

One commit, on main 00f6d7f7 (which holds #1045 and #1023). It changes two files: the family root's templates/family-root/scripts/bootstrap.py and tests/test_family_bootstrap_stops_named.py.

What changed

The signal is read from git's own trace (no token in use)

• With no token in use, git's update is already traced into a directory of the run's own (bootstrap.py (family root): after #879, two states still end family bootstrap ok beside git's exit 128: a stray gitlink inside a member's own index, and a member's gitlink at a commit no store holds #892). traced_in now reads that trace once and returns a Trace: fetched (bootstrap.py (family root): after #879, two states still end family bootstrap ok beside git's exit 128: a stray gitlink inside a member's own index, and a member's gitlink at a commit no store holds #892's work trees, as before) and died, read by the new died_in.
• died_in reads the events by the code, never git's words, as bootstrap.py (family root): after #879, two states still end family bootstrap ok beside git's exit 128: a stray gitlink inside a member's own index, and a member's gitlink at a commit no store holds #892 reads a fetch:
  • a git writes a child_start event (with the argv) and a child_exit event (with the code) for each child it starts;
  • child_of pairs the two by the writing git's sid and the child_id;
  • a child_exit whose code is 128 + N, N below signal.NSIG (died_of, now shared with ended_on), for a child whose argv begins git (git_child), is a git dead of signal N;
  • a hook or another program is not counted. Its code is its own: a post-checkout hook that exits 137 is no signal, and git checkout exits 1 over it (measured, both gits).
• The first signal is the first by the time each event gives, which is the order git met them. Where trace2 gives no time (its brief form), it is the order of the files and their lines.
  • File order alone would name the wrong one. The files go in the order their gits started, so a member's own update comes after git's update's file.
  • Measured on both gits: SIGKILL at IRRS's code leg, then SIGTERM at its spec leg. That ended IRRS's own update 143, and git's update's child_exit 143 for it came first in the files.
• signal_met chooses what (a) tells:
  • where git's update exited 0, nothing;
  • else the trace's first signal, where there is one;
  • else the update's own exit code, through ended_on as the family root's bootstrap.py: git's update killed by a signal (exit 129 and above) gives the credential advice and family bootstrap ok #998 reads it (128 + N, or -N where git itself was killed).
• Nothing where the update exited 0. It did all it set out to do then, whatever a git it ran died of on the way. Measured on both gits: a reference-transaction hook killed IRSS's git fetch after it wrote the branch, git found the commit reached, checked it out and exited 0. The run says every member and leg was fetched, as before.

What the run says

• Where the signal's code is the update's own, the line is the family root's bootstrap.py: git's update killed by a signal (exit 129 and above) gives the credential advice and family bootstrap ok #998's, word for word, so the controls read as before:

    UPDATE KILLED, and not for want of a credential: git's update ended on signal 9 (SIGKILL, exit 137), which a git it ran died of. Git's own words above say which git and where.
  family bootstrap FAILED: git's update (ended on signal 9)
  

• Where the trace gave it and the update ended with another code:

    UPDATE KILLED, and not for want of a credential: a git that git's update ran died of signal 9 (SIGKILL, exit 137), and git's update went on and ended with exit 128. Git's own words above say which git and where.
  family bootstrap FAILED: git's update (a git it ran died of signal 9)
  

• No credential advice in either case (credential_advice).

A signal and B4 both told: the signal first

• Before, fetch_members returned one failure line, the signal's or the walk's stop's. Now told_past says each that is there, each with its own failure line.
• Where both are told, the signal is said first. Why:
  • It is git's order. A death past the holder's records (128) ends git's update, so git met the signal at an earlier gitlink and went on past it.
  • Git's own words, printed just above, say them in that order too.
  • The two cures do not depend on each other.
• Measured: the killed checkout in IRRS, then B4 at IRSS, with the credential. Before, the B4 line alone was said. Now:

    UPDATE KILLED, and not for want of a credential: a git that git's update ran died of signal 9 (SIGKILL, exit 137), and git's update went on and ended with exit 128. Git's own words above say which git and where.
    UPDATE STOPPED, and not for want of a credential: git stopped at members/IRSS, whose fetch reached its remote and did not bring <commit>, ...
  family bootstrap FAILED: git's update (a git it ran died of signal 9), members/IRSS (git stopped at it)
  

• A NOT CHECKED OUT row or a whole-holder stop (unfetchable, updated_none) still comes first and alone, as for the family root's bootstrap.py: git's update killed by a signal (exit 129 and above) gives the credential advice and family bootstrap ok #998's signal (mutant S7's order is unchanged).

With a token in use: the limit, said and pinned

The issue offered two ways. I measured both, and chose to say the limit and pin it with a row.

measured (killed checkout, then IRSS's pin moved on, the token's fake value)	git 2.43.0	git 2.47.1
a directory trace target with the token's -c in argv: events holding the token	1 (the top git's start argv)	1 (the same)
the rewrite given in the environment instead, IRSS's origin an https url through a refused local proxy: events holding the token	8 (the remote helper's start and child_start events give the url)	0
an af_unix:dgram: socket target read by a thread, in memory	189 datagrams, 1 holding the token, the child_exit 137 for git checkout there; no file	194, 1, the same; no file

So:

• Any file target writes the token: in argv on both gits, and, moved to the environment, in git 2.43.0's remote helper url.
• Git's one target that is no file, a Unix socket, works, but this PR does not take it:
  • this process would have to read it for the whole update, and every git the update starts waits on it once Linux has queued 10 events (net.unix.max_dgram_qlen is 10 here), so a stalled reader hangs make bootstrap;
  • the socket's path must fit in the 107 bytes Linux takes. This harness's TMPDIR is 151 bytes, and a socket path under this session's scratchpad (114 bytes) was refused (AF_UNIX path too long);
  • git for Windows builds without it (read, not run).
    It would be a second trace mechanism, and is better as its own issue if wanted.
• What the docstrings now say:
  • ended_on: with a token in use the exit code is all there is, and a signal before a later failure is not told.
  • credential_advice: the limit and the measurement.
  • run_update: points at both.
• The row: test_with_a_credential_in_use_a_signal_is_told_only_from_git_s_code.
  • [alone]: the killed checkout alone is named, from git's own 137.
  • [then-pin-moved-on]: the killed checkout, then IRSS's pin moved on with the transport refused, is the credential's skip, the advice and ok.
  • Both: the token is in no output and no file under TMPDIR, with every caller trace on.

Two docstrings corrected

• ended_on: git's update ends with a signal's code only where no gitlink after it fails, since it keeps the last code that is not 0. (It said the update "ends with that code".)
• credential_advice: a failed fetch does not always end the update with 128. A clone that fails gives 1 and the update goes on (rv996's NIT 2 on the family root's bootstrap.py: git's update ended by a signal fails the run by name, and B4 with a token in use is told from fetches redone without a trace, so the token reaches no file (#998, #996) #1045), so the advice is dropped beside a signal even where a credential was also wanting. The run fails on the signal, and a run made again says the advice. (It said an update ending 128 + N "met none".)
• The module docstring's (a) and (c), fetch_members, run_update, fetched_in, GIT_DIED, UPDATE_KILLED and TRACE_ENV say the same.

Probes, before (main 00f6d7f7) and after (this head)

The probe is a pytest file kept out of the commit. It builds each state with tests/test_family_bootstrap_stops_named.py's own helpers, runs the family root's bootstrap.py --skip-members (offline), and records the exit code, whether the credential advice is said, and whether the fake token is in any output or any file under TMPDIR. It also runs git's own update, traced, on a copy of the same state with no token. It was run at main 00f6d7f7 and at this head, on git 2.43.0 (/usr/bin/git) and on git 2.47.1 (a local build, first on PATH). Each cell is the verdict, the signal said, and the exit code:

state (in IRRS, then in IRSS)	main 2.43.0	head 2.43.0	main 2.47.1	head 2.47.1
killed checkout, then IRSS's pin moved on, no credential	ok + advice (0)	FAILED signal 9 (1)	ok + advice (0)	FAILED signal 9 (1)
killed checkout, then IRSS's checkout refused, with the credential	ok + advice (0)	FAILED signal 9 (1)	ok + advice (0)	FAILED signal 9 (1)
killed checkout, then B4 at IRSS, with the credential	FAILED + B4 stop (1)	FAILED signal 9 + B4 stop (1)	FAILED + B4 stop (1)	FAILED signal 9 + B4 stop (1)
control: killed checkout alone, with the credential	FAILED signal 9 (1)	FAILED signal 9 (1)	FAILED signal 9 (1)	FAILED signal 9 (1)
P3, then IRSS's pin moved on, no credential	ok + advice (0)	FAILED signal 11 (1)	ok + advice (0)	ok + advice (0)
P3, then B4, with the credential	ok + advice (0)	FAILED signal 11 (1)	ok + advice (0)	ok + advice (0)
control: P3 alone, with the credential	FAILED signal 11 (1)	FAILED signal 11 (1)	ok + advice (0)	ok + advice (0)
a hook that exits 137 (no signal), then IRSS's pin moved on, no credential	ok + advice (0)	ok + advice (0)	ok + advice (0)	ok + advice (0)
a hook that exits 137, alone, with the credential	ok + advice (0)	ok + advice (0)	ok + advice (0)	ok + advice (0)
SIGKILL at IRRS, then SIGTERM at IRSS, with the credential	FAILED signal 15 (1)	FAILED signal 9 (1)	FAILED signal 15 (1)	FAILED signal 9 (1)
SIGKILL at IRRS's code leg, then SIGTERM at its spec leg, with the credential	FAILED signal 15 (1)	FAILED signal 9 (1)	FAILED signal 15 (1)	FAILED signal 9 (1)
the same two legs, then IRSS's pin moved on, no credential	ok + advice (0)	FAILED signal 9 (1)	ok + advice (0)	FAILED signal 9 (1)
token in use: killed checkout, then IRSS's pin moved on	ok + advice (0)	ok + advice (0)	ok + advice (0)	ok + advice (0)
token in use: killed checkout alone	FAILED signal 9 (1)	FAILED signal 9 (1)	FAILED signal 9 (1)	FAILED signal 9 (1)
token in use: killed checkout, then B4	FAILED + B4 stop (1)	FAILED + B4 stop (1)	FAILED + B4 stop (1)	FAILED + B4 stop (1)
token in use: killed checkout, then IRSS's checkout refused	ok + advice (0)	ok + advice (0)	ok + advice (0)	ok + advice (0)

Read across the table:

• Every no-token row of the probe that holds a signal now fails naming it, with no advice (the rows that said ok with the advice, and the one that named SIGTERM): both killed-checkout rows (pin moved on, checkout refused) on both gits, and P3 (then IRSS's pin moved on, then B4) on git 2.43.0. P3 on git 2.47.1 is not a crash there (git refuses the line and exits 128, so nothing is killed), so its rows read as before.
• Killed checkout, then B4: the B4 line alone was said at main. Now both are said, the signal first.
• A hook's own code is no signal: a post-checkout hook that exits 137 reads the same at main and at this head: ok, with the advice.
• The first signal is the first git met: SIGKILL at IRRS, then SIGTERM at IRSS (and the two legs of IRRS) named SIGTERM at main, from git's update's own last code, and name SIGKILL now.
• A signal in an update that exits 0 is not said. A reference-transaction hook that kills IRSS's git fetch once, after it wrote the ref (git then finds the commit reached, checks it out and exits 0): measured at this head on both gits (main reads no trace, so it says the same), the run says every member and leg fetched and family bootstrap ok, exit 0. The trace there holds a git fetch child_exit of 137, and the row test_a_git_killed_in_an_update_that_exits_0_is_not_said pins that nothing is said (mutant M7).
• With a token in use nothing changed, on purpose (the four token in use rows): the signal is told only where its code is git's last.
• The fake token was in no output and in no file under TMPDIR in any run of any row (probe lines token in output: False, token in temp files: []).

Tests

All in tests/test_family_bootstrap_stops_named.py (#954's and #1045's file), reusing its helpers and its style, with no assert that joins conditions with and. The module docstring gains the new rows' list, and the P3 state moved into a p3() helper so two rows build it. 11 new rows (37 before, 48 after).

The issue's Verify rows (fail at main):

• test_p3_before_a_later_failure_fails_naming_the_signal: P3, then IRSS's pin moved on, no credential, git 2.43.0: exit 1, signal 11 (SIGSEGV) named, no advice, FAILED. Skipped where git does not crash, as the family root's bootstrap.py: git's update ended by a signal fails the run by name, and B4 with a token in use is told from fetches redone without a trace, so the token reaches no file (#998, #996) #1045's P3 row is.
• test_a_killed_checkout_before_a_later_failure_fails_naming_it[pin-moved-on-no-credential] and [checkout-refused-with-the-credential]: the killed checkout (a post-checkout hook sending SIGKILL to its parent, kill -s KILL $PPID), then IRSS's pin moved on with no credential, and then IRSS's checkout refused with the credential. Each exits 1, names signal 9 (SIGKILL), gives no advice. Every POSIX git.

The choice rows (fail at main):

• test_a_signal_and_b4_after_it_are_both_named_the_signal_first: the killed checkout, then B4 at IRSS, with the credential: both lines, the signal first, and the failure line names both.
• test_the_first_signal_is_named[two-members] and [two-legs]: SIGKILL, then SIGTERM, at two members and at two legs of one member. The first by time is named (SIGKILL), where git's update's own last code, and the files' order, name SIGTERM.

The controls and the limit (pass at main, as intended, so they hold the rest as it was):

• test_a_killed_checkout_alone_is_named_as_before: the family root's bootstrap.py: git's update killed by a signal (exit 129 and above) gives the credential advice and family bootstrap ok #998's line, word for word.
• test_a_hook_s_own_code_is_no_signal: a hook that exits 137 is not a signal.
• test_a_git_killed_in_an_update_that_exits_0_is_not_said: the reference-transaction row above.
• test_with_a_credential_in_use_a_signal_is_told_only_from_git_s_code[alone] and [then-pin-moved-on]: the token's limit, pinned. Alone, the killed checkout is named from git's own 137. Then IRSS's pin moved on, the run is the credential's skip, the advice and ok, as before. Both: the fake token is in no output and in no file under TMPDIR, with every caller trace variable on.

The controls the issue names that already existed are untouched and pass: the signal alone (test_an_update_ended_on_a_signal_fails_naming_it, the P3 row), the credential's skip (test_the_credential_s_skip_is_as_it_was) and test_a_code_no_signal_gives_is_read_as_before[exit-128] and [exit-255].

Failing at main: main's bootstrap.py bytes (sha256 50a16751...) against this branch's 48-row file, git 2.43.0: 6 failed, 42 passed. The six are exactly the rows under "fail at main" above (the P3 row, the two killed-checkout rows, the both-named row and the two first-signal rows). They pass with the change.

Mutants

Each mutant applied alone to the change's bootstrap.py (a script replaces one exact string and asserts it occurs once), the stops-named file run on git 2.43.0 (/usr/bin/git) through the lane's runner, the file restored from the head's bytes and its sha256 checked after each. All on the final 48-row file (M1 to M3 were run once on the first 47 rows and again on the 48, with the same rows failing).

	mutant	result
M1	the trace read dropped (Trace(fetched_in(events)))	killed: 6 failed, 42 passed
M2	128 + N read as >= 128 (GIT_DIED <= code)	killed: 31 failed, 17 passed
M3	a child_exit of a child that is not git taken (git_child accepts any child_start)	killed: 1 failed (the hook row)
M4	the last signal for the first	killed: 2 failed (two-members, two-legs)
M5	the advice still printed beside a signal	killed: 10 failed
M6	the sort by time dropped (file order)	killed: 1 failed (two-legs)
M7	the exit-0 gate dropped (signal_met tells a signal where git exited 0)	killed: 1 failed (the reference-transaction row)
M8	a child paired by child_id alone, without the writing git's sid	killed: 1 failed (the hook row)
M9	B4 dropped beside a signal	killed: 1 failed (the both-named row)
M10	B4 said before the signal	killed: 1 failed (the both-named row)
M11	the "went on and ended with exit R" text never said	killed: 6 failed
M12	that text always said	killed: 5 failed
M13	git's update's own exit code asked before the trace	killed: 2 failed
M14	the failure line always "ended on signal N"	killed: 6 failed
M15	the child_exit kind check dropped from died_in	survives: 48 passed

M15 is equivalent, and the check stays as a reader's help. died_in only takes an event whose (sid, child_id) is one child_start named for a git, and only a child_exit event carries a code. A child_start event has none, so died_of(None) is None whether or not the kind is asked. No input reaches a different answer.

Runs

All through the lane's runner (the real gh replaced by a stub, every LANES_* variable cleared, EMAIL=service@opensoft.dev, GIT_SSH_COMMAND=false, GIT_CONFIG_GLOBAL=/dev/null), at most two at once, never the full suite. Git 2.43.0 is /usr/bin/git; git 2.47.1 is a local build, first on PATH. bootstrap.py's sha256 began f1c156e29d07e149, which the runs recorded and the committed file has (the test file's begins 1d558af665c3).

run	git	result
tests/test_family_bootstrap_stops_named.py (48 rows)	2.43.0	48 passed
the same	2.47.1	46 passed, 2 skipped (both P3 rows: that git exits 128 there, not 139)
main's bootstrap.py bytes, this branch's 48 rows	2.43.0	6 failed, 42 passed (the rows listed under Tests)
the probe, after, 17 states	2.43.0 and 2.47.1	17 passed each
group A: the stops-named file, test_family.py, test_update_shape_kept_helper.py, test_family_holder_remedies_compose.py, test_family_gitmodules_values.py, test_pinned_copy_text.py, test_repo_hygiene.py	2.43.0	707 passed
group B: test_family_holder_bootstrap_texts.py, test_family_bootstrap_gate_order.py, test_bootstrap_without_git.py, test_family_unnamed_gitlink.py, test_family_config_appends.py, test_family_member_make_jobserver.py (#1023's), test_family_siblings_bootstrap_unreadable.py, test_family_head_lost_gitmodules.py, test_family_members_not_a_list.py, test_family_makefile_siblings.py, test_bootstrap_spelling.py, test_template_text_placeholders.py, test_no_auto_maintenance.py, test_agents_md_codes.py, test_cli_reference.py	2.43.0	1010 passed, 3 skipped (GNU make's jobserver spelling here, and two rows that need a session without GIT_CONFIG_GLOBAL)
the 15 mutants	2.43.0	see Mutants

Both groups and every file that names the family root's bootstrap.py (grep -l 'family-root/scripts/bootstrap' tests/*.py gives two files, both in the groups), test_pinned_copy_text.py and the trio (test_repo_hygiene.py, test_agents_md_codes.py, test_cli_reference.py) are in those two groups. No other test pins the functions or lines this changes (a grep of tests/, docs/ and scripts/ for them finds only a docstring's mention in test_family_holder_bootstrap_texts.py, in group B, and an unrelated workflow-validator row). The runs were made at main 00f6d7f7's tree plus this change, before main moved (see Merges).

Merges

git merge-tree --write-tree of this head 73906948 (parent main 00f6d7f7), after fetching with gc.auto=0 and maintenance.auto=false:

against	result
origin/main 4a6b9afde (3 commits past 00f6d7f7)	clean (tree ad8dab73); none of the 3 touches bootstrap.py or the stops-named file
#1062 fix/1040-windows-start-errors 957ba038 (touches the family root's bootstrap.py, in git_not_started only)	clean (tree 70c5a715); the merged bootstrap.py parses, and holds died_in and #1062's 4551
#1075 fix/1055-siblings-untraced c3cf5154 (lane 5's: siblings.py, tests/test_family_siblings_untraced.py, tests/test_update_shape_kept_helper.py)	clean (tree 6770fa61); its siblings.py imports untraced from bootstrap.py, which this does not touch

The other open PRs (#1073, #1072, #1071, #1070, #1069, #1068, #1064, #1031) touch neither file.

The pinned copy

templates/family-root/scripts/bootstrap.py is in FAMILY_COPIED_VERBATIM, so each holder gets one upstream-changed row for it, as for #1045. The only import is unchanged (signal came with #998), and siblings.py's import list from it is unchanged. No Windows or macOS run was made, since CI is Linux only (#597).

Closes #1056

🤖 Generated with Claude Code

Summary by Sourcery

Report the first signal encountered by nested Git updates so family bootstrap fails with the correct cause even when later failures replace Git's exit code.

Bug Fixes:

• Make family bootstrap failures reliably report signals from nested Git commands even when later submodule failures overwrite Git's final exit code.

Enhancements:

• Preserve and analyze Git trace events to identify the first nested Git process killed by a signal, distinguish it from hook exit codes, and report it alongside later stopped submodules.
• Report multiple failure causes in Git encounter order while suppressing credential advice when a signal caused the failure.
• Document and test the tracing limitation when credentials are in use, including successful updates and non-signal hook failures.

Documentation:

• Update bootstrap behavior documentation and docstrings for trace-based signal detection, exit-code limitations, and credential-tracing constraints.

Tests:

• Add coverage for nested Git signals followed by later failures, signal ordering, hook exit-code handling, successful updates after a killed fetch, combined signal and submodule failures, and credential-in-use behavior.

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

[sourcery-ai]

Reviewer's Guide

The PR augments family bootstrap failure detection with trace2-based identification of the first nested Git killed by a signal, reports it even when later submodule failures overwrite Git's exit code, preserves non-traced credential behavior, and adds extensive regression and ordering tests.

Sequence diagram for trace-based Git signal detection

sequenceDiagram
    participant Bootstrap
    participant GitUpdate
    participant GitChild
    participant Trace2

    Bootstrap->>GitUpdate: run_update(args, root, traced=True)
    GitUpdate->>Trace2: write child_start and child_exit events
    GitChild-->>Trace2: child_exit code 128 + N
    GitUpdate-->>Bootstrap: CompletedProcess and Trace
    Bootstrap->>Trace2: died_in(events)
    Trace2-->>Bootstrap: first git child signal as Died
    Bootstrap->>Bootstrap: signal_met(returncode, trace)
    Bootstrap-->>Bootstrap: told_past(died, below, returncode)

Loading

Flow diagram for family bootstrap signal reporting

flowchart TD
    A[git submodule update] --> B{Update exit code is 0?}
    B -->|Yes| C[Report every member and leg fetched]
    B -->|No| D{Trace contains a git child signal?}
    D -->|Yes| E[Use first died_in signal]
    D -->|No| F[Use ended_on update exit code]
    E --> G[Suppress credential_advice]
    F --> G
    G --> H{stopped_below found?}
    H -->|Yes| I[told_past reports signal first, then stopped gitlink]
    H -->|No| J[Report git update failure]

Loading

File-Level Changes

Change	Details	Files
Detect nested Git processes killed by signals from Git trace2 events, preserving the first signal even when later submodule failures replace the parent update's exit code.	Parse and correlate child_start/child_exit events by parent session and child ID, considering only Git children and valid signal-derived exit codes. Select trace-derived signals before the update's own exit-code signal, while suppressing signals when the update exits successfully. Retain exit-code-only behavior when credentials disable tracing, and distinguish nested Git failures from hook processes or non-signal exits. Add Trace/Died models and refactor update tracing and signal-reporting helpers around them.	templates/family-root/scripts/bootstrap.py
Report signal failures alongside later stopped-gitlink failures in Git encounter order, with updated credential-advice behavior and diagnostics.	Emit separate failure lines for a signal and B4/stopped_below condition, placing the signal first. Describe whether the signal came from the update's own exit code or a nested Git and include the update's later exit code when applicable. Suppress credential advice whenever a traced signal is reported and document the tracing limitation when a token is in use.	templates/family-root/scripts/bootstrap.py
Expand bootstrap coverage for nested signal handling, ordering, false positives, successful updates, and token-limited tracing.	Add scenarios for killed checkouts followed by exit 128/1 failures, multiple signals, and P3 crashes. Verify hooks exiting 137 are not treated as signals and signals in exit-0 updates are ignored. Pin existing token behavior and assert credentials are absent from output and temporary trace files.	tests/test_family_bootstrap_stops_named.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1056	When the update is traced, detect a signal death of a git child wherever it occurred, even if a later gitlink failure replaced its exit code, and fail bootstrap naming the signal.	✅
#1056	Report the first signal encountered and, when applicable, report both the signal and a later stop beyond the holder's recorded gitlinks, in the specified order.	✅
#1056	Document and test the limitation when a token is in use and the update is not traced, and clarify that the update's exit code can reveal a signal only when no later gitlink failure replaces it.	✅

Possibly linked issues

• templates/family-root/scripts/bootstrap.py (#1045): a signal is told only where it is git's last failing code, so a member's crash or kill before a later 128 or 1 ends family bootstrap ok #1056: The PR implements the issue’s requested trace-based signal detection, reports the first signal alongside later stops, and tests the token-use limitation.

---

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 openRepoShape-5, 2026-10-20T21:12Z) @codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-20T21:15:50.261290Z	7390694	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 73906948ca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Handle inherited Trace2 brief mode before sorting signals

When the caller sets GIT_TRACE2_EVENT_BRIEF=1, Git omits the time field, so every event receives the same empty sort key and remains in trace-file order. For nested updates, the parent trace file can contain the propagated final signal before the child file containing the earlier signal; running GIT_TRACE2_EVENT_BRIEF=1 ... -k the_first_signal_is_named consequently reports SIGTERM instead of the first SIGKILL. Override brief mode for this private trace or reconstruct causal ordering without relying on the omitted timestamp.

Useful? React with 👍 / 👎.

[brettheap]

Independent review of #1076 (#1056) at 73906948, for lane openRepoShape-5: READY

There are no MUST or SHOULD findings, only three NITs. Each is a docstring or body wording fix; no behaviour changes.

Findings

NIT 1: one clause in credential_advice's corrected docstring is false for a member's clone (templates/family-root/scripts/bootstrap.py:859-861)

• The docstring says: "a clone that fails, a member's or a leg's, gives 1, and git's update goes on (rv996's NIT 2 on the family root's bootstrap.py: git's update ended by a signal fails the run by name, and B4 with a token in use is told from fetches redone without a trace, so the token reaches no file (#998, #996) #1045)".
• rv996's NIT 2 said this of a leg's clone only, and for a leg it is true.
• For a member's clone it is false. In git 2.47.1's builtin/submodule--helper.c, a clone that fails a second time sets suc->quickstop = 1 (:2276-2280). update_submodules then does if (suc.quickstop) { ret = 1; goto cleanup; } (:2737-2740), so no gitlink at that level is checked out after it.
• Scenario: a reader takes "goes on" to mean a member's failed clone leaves later members updated, and misreads a run.
• A related gap in ended_on (:915-918): "128 + N ... and no gitlink after it failed" is not enough on its own. A member's git submodule--helper clone killed by a signal never reaches the update's own code (it is retried, then ends in quickstop's 1), even with nothing after it. So with a token in use, a member's clone killed twice reads as the credential's skip. The trace path names it.
• Suggested wording: "a leg's clone that fails gives its member's update 1, and git's update goes on; a member's clone that fails ends it with 1 before any checkout".
• I read this from the source and did not run it.

NIT 2: the "went on" text is said where git itself was killed (bootstrap.py:964-967)

• When the update returns -N (Python's code for git itself killed) and the trace holds an earlier child's signal, the line reads: "a git that git's update ran died of signal 9 (SIGKILL, exit 137), and git's update went on and ended with exit -9."
• I got this by calling killed_said(Died(9, 137), -9) directly. No row reaches it. It needs, for example, the OOM killer taking a checkout and later the top git. The words are slightly off but harmless.

NIT 3: PR body

• The Claim: line appears twice. The live body, read with gh pr view, has 2 occurrences.
• "this session's scratchpad path (114 bytes)": the scratchpad itself is 98 bytes, so the 114 must be a socket path under it. I did not reproduce the 114.

Checked and true

1. The change does what the issue asks.

• With no token, traced_in reads the existing trace once.
• died_in matches a child_exit to its start by (sid, child_id). It takes only a child whose child_start argv begins git, and only codes 128 < code < 128 + NSIG. It picks the first by time, falling back to file order.
• signal_met says nothing where the update exited 0. Where a signal is told, credential_advice gives no advice.
• I ran traced_in on 12 synthetic trace folders ($Q/v118/rv1076/unit/probe_died_in.py):

case	result
nested gits: the parent's file first holds a later 143, the nested file an earlier 137	137 named (time order)
interleaved children of one git	the first by exit time
a child_exit with no child_start	skipped
a hook's 137 (argv is the hook path)	skipped
git-upload-pack's 141	skipped
the same child_id in two sids	not confused
brief form (no times)	file order, so the parent's 143 is named, as documented
truncated last line, non-UTF-8 bytes, a JSON line that is no dict	skipped
a file with mode 000; the folder missing	None, so the update's own exit code decides
codes 128, 193, 255, "137" (a string), 137.0 (a float)	none taken
code 192 (N = 64 < NSIG = 65)	taken

• In git 2.47.1's trace2/tr2_tgt_event.c, brief mode writes time only on version and atexit events (:98-104). So the file-order fallback really is what brief mode gets.
• In the writer's real event files (head-243.txt, head-2471.txt):
  • every non-zero child_exit code is one of 1, 128, 137, 139 or 143;
  • there is no incidental 141 (SIGPIPE);
  • the hooks' 137s carry class=hook and the hook path as argv.

2. Order and wording.

• The signal is said first, which is git's order. In update_submodules, only 128 stops the loop (:2774), and a B4 or B5 stop is 128, so any signal must come before it.
• I compared main's and the head's ended_on and killed_said for all 370 codes from -70 to 299. All 134 signal codes give byte-identical text (0 differences), and ended_on is the same everywhere. The failure line is unchanged where the code is the update's own.

3. Token in use.

• The [then-pin-moved-on] row holds the limit: exit 0, the advice alone, with a token. Both new rows assert the token is in no output and no file under TMPDIR, with every caller trace on.
• My mutant R3 (traced even with a token) failed 9 rows, both new ones among them: the token reached the caller's trace2-normal.txt and trace2-perf.txt.
• The choice and its reasons hold, as far as I read them:
  • the argv -c lands in the top git's start event;
  • in the 2.43 token probe, git remote-https children are started with argv beginning git;
  • net.unix.max_dgram_qlen is 10 here.

4. Rows.

• 37 rows before, 48 after (24 to 32 def test_).
• No assert joins conditions with and or or. New lines are 79 characters at most, ASCII only.
• flake8 shows only the 3 findings already on main for bootstrap.py, and only F811 for the test file.
• Main's bootstrap.py (sha256 50a16751…) against the 48 rows: 6 failed, 42 passed. The six are exactly the body's six.
• The P3 rows skip only where git's own update does not exit 139: they skip on 2.47.1 ("exits 128 here") and run on 2.43.0.

5. Mutants (stops-named file, git 2.43.0, file restored by sha256 after each)

mutant	result
M1, trace read dropped (writer's)	killed: 6 failed, 42 passed
M2, >= 128 (writer's)	killed: 31 failed, 17 passed
M3, non-git child taken (writer's)	killed: 1 failed (the hook row)
R1, last signal named instead of the first	killed: 2 failed (two-members, two-legs)
R2, any child_exit taken, start not required	killed: 1 failed (hook row)
R3, trace read with a token in use	killed: 9 failed
R4, the NSIG upper bound dropped	killed: 1 failed (exit-255)
R5, "git" matched as a substring of argv[0]	killed: 1 failed (hook row)
R6, time compared to the second only	killed: 1 failed (two-legs); this kill depends on the events falling in one second
R7, "exit" said with the update's code	killed: 6 failed
R8, only checkout or fetch children taken	killed: 1 failed (the P3 row; that kill exists only on 2.43)

• M15 is equivalent. Only child_exit, exit and atexit events carry code. The last two have no child_id, so their key (sid, "None") never matches a child_start. A child_start has no code. No input git writes reaches a different answer.

6. Runs (through run9.sh, with EMAIL, GIT_SSH_COMMAND=false and GIT_CONFIG_GLOBAL=/dev/null exported)

• git 2.43: the stops-named file, 48 passed.
• git 2.47.1 (git --version printed git version 2.47.1 from $Q/v115/w764/git247/bin/git): 46 passed, 2 skipped (the two P3 rows).
• git 2.43: test_family_member_make_jobserver.py, test_family.py, test_pinned_copy_text.py and the trio: 483 passed, 1 skipped (the jobserver spelling).

7. Merges (git merge-tree --write-tree, all clean, trees as the body gives)

• origin/main 4a6b9afde (3 commits past 00f6d7f7): ad8dab73.
• validate-family.py, validate-pins.py and both bootstrap.py copies: a git Windows cannot start for a reason other than 193 that names no file (winerror 216, 1260, 11, or 188-202) is git-not-runnable, exit 2, with the put-git-on-PATH remedy, where each ended in a traceback, exit 1 (#1040) #1062 957ba0386: 70c5a715. The merged bootstrap.py parses and holds both died_in and 4551.
• the family root's siblings.py: with a token in use, the clone and the fetch that carry it run in bootstrap.py's untraced() environment, so make siblings and family.py siblings write the token to no trace the caller asks git for (#1055) #1075 c3cf51544: 6770fa61. All six names siblings.py imports from bootstrap.py resolve.
• Nothing else in the repo imports a function whose signature changed.
• The SonarCloud quality gate for PR 1076 is OK, with 0.0% new duplication.

8. Title and body

• The title is 243 characters, is the commit subject, and is true.
• The only closing keyword is Closes #1056; closingIssuesReferences is [1056].
• The sha256 of bootstrap.py begins f1c156e29d07e149 and the test file's 1d558af665c3, as the body says.
• Cognitive complexity by hand: fetch_members 12, died_in about 8, every other changed function 4 or less.

Could not verify

• Body numbers I did not reproduce:
  • group A 707 and group B 1010 passed, 3 skipped (I ran the brief's file set instead);
  • the probe's 17 passed on each git (I read the logs);
  • the token table's 1/1, 8/0 and 189/194 datagrams (read from token.txt);
  • TMPDIR 151 bytes;
  • M4 to M14 and M15's run;
  • that the 8 other open PRs touch neither file.
• How git 2.43's source handles a member's clone (only the 2.47.1 source was read).
• Real https credential failures: whether any git child dies of SIGPIPE there, which would now fail the run where it said ok.
• Windows and macOS.

Checklist candidates

1. A signal git recovered from now fails the run. A fetch killed after writing its ref, or a clone killed and then retried, beside a later credential failure, now fails naming the signal with no advice. Only the exit-0 case is pinned.
2. Two unmeasured ways to trace with a token in use. A credential helper that reads the token from the environment keeps it out of argv and the url. A FIFO target would have the same reader drawback as the socket.
3. Brief-form trace2 is unpinned. It names a parent's later code, as documented.

Scratch left

• Notes, mutant logs and scripts: /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad/v118/rv1076/.
• Basetemps: /tmp/claude-1000/-workspace-projects-openRepoShape/50cede29-ab82-4ca3-9f67-d98e1a58c8d2/scratchpad/v110/bt/rv1076-*.
• The three worktrees are removed and the refs/l5rv/rv1076-* refs deleted. Nothing of mine is running; the w912 pytest runs on the host belong to another agent.