🩺 Stability & Availability | 🔴 Critical | 🏗️ Heavy lift

#!/bin/bash
# Locate any unsafe Sync/Send impls for the frame types.
rg -nP -C4 'unsafe\s+impl\s+(Sync|Send)\s+for\s+(InterpreterFrame|FrameObject|FrameUnsafeCell)' crates/vm/src

# List every cold() call site with context to classify owner-thread vs cross-thread.
rg -nP -C3 '\.cold\(\)' crates/vm/src

# Check which FrameObject getters guard with check_locals_access.
rg -nP -C6 'fn (f_trace|set_f_trace|f_trace_lines|set_f_trace_lines|f_trace_opcodes|set_f_trace_opcodes)\b' crates/vm/src/builtins/frame.rs

#!/bin/bash
set -euo pipefail

# Inspect the unsafe Sync impl context and the cold() accessor.
sed -n '860,900p' crates/vm/src/frame.rs
sed -n '1260,1290p' crates/vm/src/frame.rs

# Inspect the FrameObject definitions and any unsafe Sync for frame object storage.
rg -n -C3 'struct FrameObject|type FrameObject|unsafe impl (Sync|Send)|pyclass|PyAtomic' crates/vm/src/frame.rs

# Inspect VM current_frame and owner checks around frame access.
sed -n '1130,1165p' crates/vm/src/frame.rs
rg -n -C4 'fn current_frame|current_frame\(' crates/vm/src/vm/mod.rs crates/vm/src/frame.rs

# Read only relevant source definitions and call sites with enough context to see guard usage.
sed -n '620,750p' crates/vm/src/builtins/frame.rs
sed -n '2100,2130p' crates/vm/src/vm/mod.rs
sed -n '2368,2385p' crates/vm/src/vm/mod.rs
sed -n '830,920p' crates/vm/src/builtins/frame.rs

Make cold() race-safe on FrameObject payloads.

cold() writes a value into UnsafeCell<Option<Box<FrameColdData>>> through a shared reference. The frame types are marked Send/Sync, and tracing/accessor methods such as f_trace, set_f_trace, f_trace_lines, set_f_trace_lines, f_trace_opcodes, and set_f_trace_opcodes reach it from any thread holding the FrameObject without ownership/STW guards before allocation. Concurrent first access can allocate two boxes and leave Py<FrameObject> with a reference to an unshared/dropped value.

Restrict lazy allocation to owner-thread or STW contexts, or publish the FrameColdData pointer atomically so initialization is race-free.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/frame.rs` around lines 871 - 881, Make the lazy initialization
performed by FrameObject::cold race-safe instead of mutating
UnsafeCell<Option<Box<FrameColdData>>> through a shared reference. Either
enforce owner-thread/STW-only access before allocation across cold() and its
tracing/accessor callers, or replace the storage and publication path with
atomic initialization that guarantees one shared FrameColdData allocation is
retained and visible to concurrent readers.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

#!/bin/bash
# Find every match on ExecutionResult across the workspace.
rg -nP -C4 'ExecutionResult::' crates

#!/bin/bash
set -euo pipefail

echo "== ExecutionResult declaration and exports/usages =="
rg -n 'pub enum ExecutionResult|ExecutionResult' crates/vm/Cargo.toml crates/vm/src -g '*.rs' | head -200

echo
echo "== workspace Cargo references to vm crate =="
rg -n 'rustpython[-_ ]?vm|rustpython_vm|vm]' Cargo.toml crates/*/Cargo.toml crates/*/*/Cargo.toml 2>/dev/null || true

echo
echo "== match expressions that might pattern-match ExecutionResult without ExecutionResult:: =="
python3 - <<'PY'
import pathlib, re
for p in pathlib.Path('crates').rglob('*.rs'):
    text=p.read_text(errors='ignore')
    if 'ExecutionResult' not in text:
        continue
    for i,line in enumerate(text.splitlines(), start=1):
        if 'ExecutionResult' in line:
            print(f"{p}:{i}:{line}")
PY

echo
echo "== public exports context =="
sed -n '1,200p' crates/vm/src/lib.rs
sed -n '1420,1445p' crates/vm/src/frame.rs
sed -n '80,112p' crates/vm/src/coroutine.rs

#!/bin/bash
set -euo pipefail

echo "== candidate release notes files =="
fd -i 'rename|release|changelog|news|changes' . -t f -x sh -c 'echo "--- $1"; sed -n "1,220p" "$1"' sh {}

echo
echo "== TailCall mentions across tracked files =="
rg -n 'TailCall|tailcall|execution result|ExecutionResult' . --glob '!target/**' --glob '!__pycache__/**' | sed -n '1,240p'

Record the ExecutionResult::TailCall public API addition.

ExecutionResult is public, so external downstream crates that exhaustively match on it will need to handle TailCall. Update the release/compat notes for this breaking API change.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/frame.rs` around lines 1455 - 1458, Update the release or
compatibility notes to record the public ExecutionResult::TailCall variant
addition and identify it as a breaking API change requiring downstream
exhaustive matches to handle the new variant.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

#!/bin/bash
# Show the monitoring fires in the recursive unwind path.
rg -nP -C3 'EVENT_PY_UNWIND|fire_py_unwind|EVENT_RERAISE|fire_reraise' crates/vm/src

# Check whether tail-call eligibility consults monitoring state.
rg -nP -C6 'tailcall_enabled|is_generator_like|specialization_eval_frame_active' crates/vm/src/frame.rs

#!/bin/bash
set -euo pipefail

# Inspect the recursive unwind/trace handling and trampoline setup, plus monitoring event handling.
sed -n '2160,2275p' crates/vm/src/frame.rs
sed -n '2320,2380p' crates/vm/src/frame.rs
sed -n '3130,3230p' crates/vm/src/frame.rs
sed -n '3425,3470p' crates/vm/src/frame.rs

# Inspect monitoring event fire helpers.
sed -n '960,1035p' crates/vm/src/stdlib/sys/monitoring.rs

# Inspect tailcall_prepare_frame guard locations.
rg -n "tailcall_prepare_frame|is_generator_like|specialization_eval_frame_active" crates/vm/src/frame.rs

#!/bin/bash
set -euo pipefail

# Inspect the trampoline call instruction implementation, tailcall preparation, and resume path.
sed -n '5800,5865p' crates/vm/src/frame.rs
sed -n '10090,10145p' crates/vm/src/frame.rs
sed -n '2280,2320p' crates/vm/src/frame.rs

# Inspect where RunIfResume instructions or suspended frames re-enter the trampoline.
rg -n -C4 'RunIfResume|trampoline_handle_exception|resume\(' crates/vm/src/frame.rs

Fire PY_UNWIND monitoring in trampoline_handle_exception.

In recursive frame execution, monitoring::fire_py_unwind is fired when the exception escapes the frame. The trampoline path does not enable tailcall_enabled, so tail-call preparation is skipped and sys.settrace is unaffected, but sys.monitoring still reads vm.state.monitoring_events and expects monitoring events. If this path is reachable with EVENT_PY_UNWIND enabled, emit fire_py_unwind here with idx as u32 * 2 before returning to unwind_blocks.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/frame.rs` around lines 2308 - 2369, Update
trampoline_handle_exception to emit monitoring::fire_py_unwind when
EVENT_PY_UNWIND is enabled, using the computed call-site offset idx as u32 * 2,
immediately before invoking unwind_blocks. Preserve the existing traceback setup
and unwind result propagation.

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Extract the repeated ExecutingFrame construction.

The same construction block now appears four times: Py<FrameObject>::with_exec, Py<FrameObject>::yield_from_target, trampoline_handle_exception, and run_iframe. The blocks differ only in builtins_dict and tailcall_enabled. Add one constructor, for example ExecutingFrame::from_iframe(iframe, tailcall_enabled, resolve_builtins_dict, vm), and call it from all four sites.

As per coding guidelines: "When branches differ only in a value but share logic, extract the differing value and invoke the common logic once."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/frame.rs` around lines 2321 - 2350, Extract the duplicated
ExecutingFrame initialization into a shared constructor such as
ExecutingFrame::from_iframe, accepting iframe, tailcall_enabled,
resolve_builtins_dict, and vm. Replace the construction blocks in
Py<FrameObject>::with_exec, Py<FrameObject>::yield_from_target,
trampoline_handle_exception, and run_iframe, passing each site’s differing
builtins_dict behavior and tailcall_enabled value while preserving all existing
field assignments.

Source: Coding guidelines

📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Merge the two tail-call preparation functions.

tailcall_prepare_frame and tailcall_prepare_bound_method_frame share the locals selection, the new_on_datastack call, the argument move loop, and the pending-ref publication. They differ only in where the callee function comes from and what fills fastlocals[0].

Extract one helper that takes the resolved &Py<PyFunction>, the number of stack arguments, and an optional self value, then let both call sites supply those three values.

As per coding guidelines: "When branches differ only in a value but share logic, extract the differing value and invoke the common logic once."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/frame.rs` around lines 10604 - 10726, Merge
tailcall_prepare_frame and tailcall_prepare_bound_method_frame by extracting a
shared helper that accepts the resolved PyFunction, stack argument count, and
optional self value. Move the shared locals creation, datastack frame
construction, fastlocals population, stack cleanup, and pending-tailcall
publication into that helper. Update both existing methods to resolve their
function and self values, then delegate while preserving ownership transfer for
the callable and bound-function references.

Source: Coding guidelines

🩺 Stability & Availability | 🔴 Critical | 🏗️ Heavy lift

The prepared callee frame leaks its data-stack allocation if this function unwinds.

InterpreterFrame::new_on_datastack reserves the callee frame at line 10635. vm.set_pending_tailcall publishes it at line 10668. Between those two points the frame is owned by nobody:

• self.pop_multiple(nargs as usize) panics on stack underflow.
• Overwriting a fastlocal slot drops the previous value, and a __del__ implementation can panic.

If either happens, the callee allocation stays on the data stack and release_datastack_frame never runs. The trampoline never sees the frame, so it cannot clean it up either. Compare PyFunction::invoke_prepared_exact_args in crates/vm/src/builtins/function.rs, which pairs the allocation with an unconditional release.

Guard the region, for example with scopeguard::guard that releases the callee frame and pops the base on unwind, and disarm the guard after set_pending_tailcall succeeds. The same gap exists in tailcall_prepare_bound_method_frame at lines 10697-10724.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/frame.rs` around lines 10635 - 10668, The prepared callee frame
is not cleaned up if argument transfer unwinds before publication. In the
frame-preparation flow around InterpreterFrame::new_on_datastack and
vm.set_pending_tailcall, add an unwind guard that releases the callee data-stack
frame and restores the caller stack base, then disarm it only after
set_pending_tailcall succeeds; apply the same protection to
tailcall_prepare_bound_method_frame.

🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift

The fast-call path has no unwind-safe frame teardown. with_iframe now guards exit_iframe with scopeguard, but the datastack fast-call path does not. If run_iframe unwinds, the frame stays on the thread-local frame chain, recursion_depth stays incremented, and the datastack allocation is never popped or dropped.

• crates/vm/src/vm/mod.rs#L1424-L1442: wrap entry_state in a scopeguard around the crate::frame::run_iframe call, and apply the same protection to the run_iframe calls and the suspended frame_stack inside run_frame_fast_trampoline.
• crates/vm/src/builtins/function.rs#L632-L650: guard the iframe so release_datastack_frame and vm.datastack_pop(base) run when vm.run_frame_fast unwinds.
• crates/vm/src/builtins/function.rs#L803-L827: apply the same guard around vm.run_frame_fast(iframe) in invoke_prepared_exact_args.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/vm/mod.rs` around lines 1424 - 1442, The fast-call execution
paths need unwind-safe cleanup. In crates/vm/src/vm/mod.rs lines 1424-1442,
guard entry_state with scopeguard around crate::frame::run_iframe, including
each run_iframe call and suspended frame_stack handling in
run_frame_fast_trampoline. In crates/vm/src/builtins/function.rs lines 632-650,
guard the iframe so release_datastack_frame and vm.datastack_pop(base) execute
if vm.run_frame_fast unwinds; apply the same protection around
vm.run_frame_fast(iframe) in invoke_prepared_exact_args at lines 803-827.

📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift

Extract the repeated caller-teardown sequence into a helper.

The block drop(_caller_refs); self.exit_iframe(...); if !caller_is_entry { unsafe { if let Some(base) = ...release_datastack_frame() { self.datastack_pop(base); } } } appears six times, and the TailCall re-push block appears three times. The repetition makes it easy to omit one step in a future change, and each omission is a memory-safety defect rather than a cosmetic one.

Add two private helpers on SuspendedFrame or on the trampoline scope, for example finish_frame(&self, entry, iframe_ptr, is_entry) and resuspend(&self, stack, iframe_ptr, entry, is_entry), then call them from every arm.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/vm/mod.rs` around lines 1534 - 1686, Extract the repeated
caller cleanup into a private helper associated with SuspendedFrame or the
trampoline scope, preserving the order of dropping owned references, calling
exit_iframe, and conditionally releasing and popping the datastack frame;
replace every duplicated cleanup block in ReturnValue and Unwind handling. Also
extract the repeated TailCall SuspendedFrame re-push logic into a helper and use
it in all three TailCall arms, preserving pending-tailcall reference draining
and callee transfer.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

retained_back is overwritten unconditionally here, unlike every other write site.

with_frame (Line 2118), release_datastack_frame, and the f_back chain walker all guard the write with if guard.is_none(). exit_iframe replaces the existing value. If the frame already captured a caller reference during execution, this write discards it and installs the materialize_chain result. Confirm that replacement is intended; otherwise use the same is_none guard for consistent f_back results.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/vm/mod.rs` around lines 2249 - 2253, Update the retained_back
assignment in exit_iframe to preserve an existing caller reference: lock
retained_back, assign the materialize_chain result only when the guard is None,
and leave the existing value unchanged otherwise. Keep the old_chain check and
frame materialization flow intact.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Run cargo fmt; Line 2388 exceeds the default rustfmt width.

The condition on Line 2388 is a single long line. Default rustfmt wraps it. Reformat the file before merge.

Note also that cold() allocates the cold block on first access. This check runs on the return path of every traced frame, including frames that only have a profile function and never set trace. Reordering the condition to test self.profile_func first would avoid that allocation.

As per coding guidelines: "Follow default rustfmt style and run cargo fmt for Rust code."

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/vm/src/vm/mod.rs` around lines 2387 - 2389, Reformat the condition in
the traced-frame return path with default rustfmt, and reorder its operands to
check self.is_none(&self.profile_func.borrow()) before accessing
frame.iframe().cold().trace, avoiding unnecessary cold-block allocation for
profile-only frames while preserving the existing logic.

Source: Coding guidelines