Skip to content

Require Orderly SIGINT and SIGTERM Handling in Shell and Python Scripts - #4078

Merged
ptr727 merged 12 commits into
developfrom
feature/codestyle-interrupts
Nov 11, 2026
Merged

ptr727 merged 12 commits into
developfrom
feature/codestyle-interrupts

Conversation

@ptr727

@ptr727 ptr727 commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

Summary

Adds the narrowed SIGINT and SIGTERM rule the maintainer chose on #3947 (option 1, answered 2026-11-10).

  • CODESTYLE.md General gains an "Interrupts" subsection after "Operations and Failure Messages". A Bash or Python script releases its temporary paths, locks, and child processes on SIGINT or SIGTERM. It writes persistent state through a temporary path and a rename. It prints one line naming the signal, with no traceback, and exits 130 or 143. The rule applies when a script is created or next edited, with no retrofit sweep. Only a script holding a lock, temporary state, or a child process owes a test that signals it mid-run, and that test is skipped on Windows.
  • CODESTYLE.md Python gains "Interrupts in Python": a SIGTERM handler maps the signal onto KeyboardInterrupt, and the entry point catches that exception once.
  • CODESTYLE.md Shell gains "Interrupts in Shell": cleanup runs in the EXIT trap, and the INT and TERM traps stop children and keep the status.
  • The python-codestyle and shell-codestyle skills carry these sections as generated includes, regenerated with scripts/build_dist.py. Each skill's description names the rule, and python-codestyle's stays within the 1024-character limit.

Mechanics stated for the answer's rules

These implement the answer's rules rather than adding new ones. They are listed so reviewers can check them:

  • Every Bash script sets the INT and TERM traps, and they also print the signal line. A trap is the only place a shell script knows which signal ended it, and without one a childless script would print nothing.
  • The traps send SIGTERM to children and wait for them, with || : on both and 2>/dev/null on kill. The children's process IDs sit in an array set to () before the traps, and the trap skips both while ${#pids[@]} is 0. On Bash 3.2 under set -u, a constructed check showed that count works on an empty array while ${pids[*]} fails. A background child ignores SIGINT. Under set -eu, a failed kill or wait, or an unset variable, would end the trap before the line prints.
  • A long-running external command runs in the background under wait "$pid", so its status still reaches set -e, with <&0 when it reads standard input. The trap's kill reaches only the process $! names. So a function, a group, a subshell, a pipeline, or sh -c runs in the foreground, where the trap runs once the interrupted command returns. Only the script's own shell starts a background child, so the child reaches the script's array and its wait. Bash runs a trap only after a foreground command returns, while a trapped signal ends a wait at once.
  • A subprocess.Popen child runs without shell=True and is terminated and waited for in a finally clause, since leaving its with block does not stop it. A lower Python handler that catches KeyboardInterrupt re-raises it. The rename uses os.replace, since os.rename fails on Windows when the target exists.

Generator fix (pre-existing defect this change exposes)

"Interrupts in Shell" is the last heading in CODESTYLE.md. An include of a file's last heading also copied that file's trailing link-reference definitions into the skill, which failed markdownlint MD053 in every copy. This is a pre-existing defect in scripts/build_dist.py, fixed here because this change needs it. A body that runs to the end of its file now ends before those trailing definitions and their grouping comments. Nothing else about region extraction changes. tests/test_build_dist.py adds a test that fails on develop and passes here, plus a guard showing that a trailing comment with no definitions after it is kept.

Verification

  • scripts/build_dist.py --check: current.
  • tests/test_build_dist.py: all tests pass. The new trailing-definitions test fails against develop's generator.
  • Prose gate (--diff origin/develop), repo gate, ruff, and the Docker markdownlint and editorconfig-checker runs: all clean.
  • The bash trap behavior was checked with constructed probe scripts. The EXIT trap runs when SIGINT or SIGTERM ends the script. A background child outlives the script unless an INT or TERM trap stops it. With the stated trap, SIGINT exits 130 and SIGTERM exits 143, each printing its line and leaving no child running.

Declined local-pass findings

  • scripts/build_dist.py, introduced: a pass read "A script takes this rule when it is created or next edited" as binding this script now, since this pull request edits it. Declined. The rule binds an edit made after it is on develop, and this pull request is the one that lands it. The maintainer's answer also rules out a retrofit sweep. So the script's next edit owes the rule, and the generator fix here stays limited to ending a body before the trailing definitions.
  • .agents/skills/skill-lifecycle/SKILL.md line 28, introduced: a pass called its account of where an include body ends stale. Declined. It describes a body that ends at a heading, which is unchanged, and heading_body's docstring now states the end-of-file case.
  • CODESTYLE.md "Interrupts in Shell" and "Interrupts in Python", introduced: a pass noted that an external command which starts children of its own and does not pass SIGTERM on, such as find -exec, leaves those children running. Declined. The decision names the children the script started, and a command's own children are that command's to stop.
  • spec/fidelity_text.py, introduced design finding: a pass suggested taking definition extents from the parser token's line map. Declined. The scan reuses link_definitions for where each definition starts. The only shape it misreads is a paragraph line directly after a trailing definition, which this repository's Markdown never has.

Closes on promotion: #3947

🤖 Generated with Claude Code

ptr727 and others added 3 commits November 11, 2026 10:21
Add an "Interrupts" rule to CODESTYLE.md General, with the Python and
Shell mechanics in their own sections, per the maintainer's answer on
the issue. The python-codestyle and shell-codestyle skills carry the
sections as generated includes.

The shell mechanics are the last section of CODESTYLE.md, which exposed
a generator defect: an include of a file's last heading also copied the
file's trailing link-reference definitions. build_dist.py now ends such
a body before them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Send SIGTERM to a shell script's children and wait for them, since a
background child ignores SIGINT. Every shell script sets both traps, so
one with no children still prints the line and keeps the status. A
Python script exits 130 unless its SIGTERM handler recorded a signal,
and waits for a terminated Popen child. Drop the generator's marker and
code-block branches, which no case reaches, and state the end-of-file
case in heading_body's docstring.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Discard the trap's kill and wait statuses so errexit cannot end it
before the signal line prints, give a stdin-reading background child
its input with <&0, let a lower Python handler re-raise rather than
forbidding it, and name os.replace for the rename.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings November 11, 2026 18:36
@ptr727

ptr727 commented Nov 11, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head 364b67f849770cfeafdf4411dc4bd7ca8f6354ac, the content this pull request carries at that commit against develop, and it recorded 3 findings.

@coderabbitai

coderabbitai Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
Pre-merge checks: Passed 1 · Inconclusive 1

Failed Failed checks: 1 inconclusive

Check name Status Explanation Resolution
Title check Pending This assessment has not completed. The check will be retried on the next pre-merge check run.
Passed Passed checks: 1 passed

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Name Bash rather than shell, so a PowerShell script is not read as
owing the rule. Skip the signal-mid-run test on Windows, which cannot
deliver either signal for a script to handle. Say a script with no
children skips the trap's kill and wait, and quiet kill for a child
that already exited so the trap prints one line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Approval is blocked by an active moderate issue in trailing link-definition extraction, along with unresolved documentation and cross-platform edge cases.

4 open issues
What changed in this PR

This PR adds orderly SIGINT and SIGTERM handling requirements for Bash and Python scripts, updates the canonical coding guidance and generated Skills, and fixes trailing link-reference extraction in the Skill generator.

Changes:

  • Adds general, Python-specific, and Bash-specific interrupt-handling rules.
  • Regenerates authored and distributed Skills with updated guidance and source digests.
  • Prevents trailing link-reference definitions from being copied into generated regions, with regression tests.
File Description
tests/​test_build_dist.py Adds regression tests for trimming trailing link definitions and preserving unrelated trailing comments.
scripts/​build_dist.py Updates region extraction to exclude trailing document-level link definitions from generated sections.
CODESTYLE.md Defines general, Python, and Bash interrupt-handling requirements.
.github/​skills/​shell-codestyle/​SKILL.md Regenerates the GitHub Copilot shell-codestyle Skill with interrupt guidance.
.github/​skills/​python-codestyle/​SKILL.md Regenerates the GitHub Copilot python-codestyle Skill with interrupt guidance.
.claude-plugin/​fleet-skills/​skills/​shell-codestyle/​SKILL.md Regenerates the Claude shell-codestyle Skill with interrupt guidance.
.claude-plugin/​fleet-skills/​skills/​python-codestyle/​SKILL.md Regenerates the Claude python-codestyle Skill with interrupt guidance.
.claude-plugin/​fleet-skills/​.source-digests/​shell-codestyle Updates the source digest for the shell-codestyle Skill.
.claude-plugin/​fleet-skills/​.source-digests/​python-codestyle Updates the source digest for the python-codestyle Skill.
.agents/​skills/​shell-codestyle/​SKILL.md Updates the authored shell-codestyle Skill with interrupt guidance.
.agents/​skills/​python-codestyle/​SKILL.md Updates the authored python-codestyle Skill with interrupt guidance.

Review effort: Lite

Comment thread scripts/build_dist.py Resolved
Comment thread CODESTYLE.md Resolved
Comment thread CODESTYLE.md Resolved
Comment thread CODESTYLE.md Resolved
A signal arriving before the first child starts would otherwise expand
an unset variable inside the trap, which nounset turns into an exit
before the signal line prints.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.30%. Comparing base (dc6bca5) to head (da611c0).
⚠️ Report is 2 commits behind head on develop.

Additional details and impacted files
@@             Coverage Diff             @@
##           develop    #4078      +/-   ##
===========================================
- Coverage    82.34%   82.30%   -0.05%     
===========================================
  Files           38       38              
  Lines        12951    12961      +10     
===========================================
+ Hits         10664    10667       +3     
- Misses        2287     2294       +7     
Flag Coverage Δ
python-3.13 82.30% <100.00%> (-0.05%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

An emptiness test that expands an empty array is an unbound-variable
error under set -u on Bash before 4.4, while a count is not. A bare
wait returns 0 whatever the child's status, so name the ID it waits on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ptr727

ptr727 commented Nov 11, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head f36ebaaf8290369db4ce5e64fe6ee28a655b9a4d, the content this pull request carries at that commit against develop, and it recorded 1 finding.

ptr727 and others added 3 commits November 11, 2026 10:52
A background function, group, or subshell is a Bash subshell, and a
SIGTERM to it leaves its own command running. A Popen child under
shell=True has the same gap, so run it without the shell.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
State the rule by the property: a shell running other commands, sh -c
and a pipeline included, runs in the foreground, where the trap waits
for it rather than orphaning its commands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A backgrounded pipeline has no shell around it, but the trap's kill
still reaches only the process $! names, so that is the reason stated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ptr727

ptr727 commented Nov 11, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head 13dbd1b4935d028967689890147a5532d720948e, the content this pull request carries at that commit against develop, and it recorded 1 finding.

ptr727 and others added 3 commits November 11, 2026 11:03
A function or a group runs in the script's own shell, so the trap runs
once the command it interrupted returns rather than after every command
in it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A subshell or a pipeline element resets caught traps, so a child it
backgrounds is one no trap stops.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The child misses the script's process ID array and its wait, which is
what fails on a SIGTERM sent to the script alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ptr727

ptr727 commented Nov 11, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head da611c04327ddb0a241feef84559539bd483d18a, the content this pull request carries at that commit against develop, and it recorded 0 findings.

@ptr727
ptr727 merged commit 5f15e2f into develop Nov 11, 2026
12 of 13 checks passed
@ptr727
ptr727 deleted the feature/codestyle-interrupts branch November 11, 2026 19:31
ptr727 added a commit that referenced this pull request Nov 12, 2026
…s Rule, Companion-Free Lint, Root hub_fetch_run, .codecov.yml (#4083)

## Summary

Promotes burndown round 3 of the attended run of 2026-11-10, together
with two pull requests from other hub sessions, from `develop` to
`main`.

- #4082: `configure.sh apply` refuses a repository the registry does not
list, before any write. A repository whose entry is on `develop` but not
yet on `main` is configured and audited from a hub checkout at
`develop`. `OPERATIONS.md`, `AUDIT.md`, `GOVERNANCE.md` "Hub-Hosted
Tooling", and the standup, audit, and branch-protection skill text now
say so.
- #4081: `WORKFLOW.md`'s contradictory trigger, merge, and release rules
are reconciled. D1.5 requires a gate to trigger on `pull_request`, and
the audit reports a gate that does not. A retarget is cleared by a push
or a close and reopen.
- #4078: `CODESTYLE.md` gains an Interrupts rule with Python and Shell
mechanics. `build_dist.py` no longer carries a file's trailing link
definitions into an include of its last heading.
- #4076: `docker_lint.py` imports only the standard library, so the Lint
tasks fetch no companions. The provenance label and the ruff task labels
are corrected. `GOVERNANCE.md` "Repo-Scoped Secrets" states the
owner-first host secret stem.
- #4080, from another session: `hub_fetch_run.py` lives in the
repository root for both hook shapes.
- #4077, from another session: only `.codecov.yml` is accepted as the
Codecov configuration name.

Fixes #4061
Fixes #4011
Fixes #4051
Fixes #4048
Fixes #4060
Fixes #3947
Fixes #4072
Fixes #3915
Fixes #4059
Fixes #4071

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

<!-- coderabbit-ai-generated:v1 -->

## Summary by CodeRabbit

* **Documentation**
* Clarified when repository checks and configuration use the `develop`
branch, and documented that configuration changes are not applied to
unregistered repositories.
* Expanded scripting guidance for handling interruptions, cleaning up
resources, and saving persistent state safely.
* Updated workflow, coverage, and hook setup guidance to reflect current
requirements and locations.

* **Bug Fixes**
* Audits now check only the declared baseline filename; repositories
using a different filename are reported as missing.
* Markdown heading extraction no longer includes trailing link
definitions in the heading body.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants