Support free-threaded python 3.13+

[benfred]

Python 3.13 adds the ability to have a free-threaded python interpreter - which doesn't have a GIL.

py-spy doesn't currently work against free-threaded python interpreters, because:

• PyObject layout is different : instead of just containing a ob_refcnt and ob_type members - with Py_GIL_DISABLED interpreters the PyObject has additional members (threadid/mutex/ etc)
• MANAGED_DICT_OFFSET is different

[honglei]

py-spy CPython 3.14t/free-threaded support plan

Purpose

This document is a proposed upstream-facing implementation plan for CPython
3.14 free-threaded (3.14t) support in py-spy.

The goal is not only to make a local prototype work. The goal is to give the
maintainer a reviewable path from a minimal record/dump fix to a
well-bounded, testable implementation that does not regress the existing
CPython 3.12, 3.13, and ordinary 3.14 GIL builds.

Source line references below are based on the current local worktree
/home/honglei/bwh/py-spy-issue711. Recheck them against the final PR branch
before posting upstream.

Current py-spy architecture

py-spy is an out-of-process profiler. It opens the target process, parses the
main Python binary and optional libpython, then reads CPython interpreter
state directly from target memory.

Important existing code paths:

• PythonProcessInfo::new() finds executable and libpython mappings, then
  parses symbols and BSS ranges.
  • src/python_process_info.rs:144-197
• Python version and interpreter address are resolved in
  get_python_version() / get_interpreter_address().
  • src/python_process_info.rs:344-393
• PythonSpy::new() creates the process reader, detects the Python version,
  resolves the interpreter and thread state address, and constructs optional
  native unwinding state.
  • src/python_spy.rs:50-107
• PythonSpy::get_stack_traces() dispatches by (major, minor) to a concrete
  compile-time InterpreterState implementation.
  • src/python_spy.rs:170-197
• Version-specific object access is expressed as Rust traits in
  src/python_interpreters.rs.
  • InterpreterState, ThreadState, FrameObject, CodeObject,
    BytesObject, StringObject, TupleObject, ListObject, Object,
    TypeObject: src/python_interpreters.rs:20-113
• Stack walking is generic over those traits.
  • get_stack_traces(): src/stack_trace.rs:72-117
  • get_stack_trace(): src/stack_trace.rs:120-180
• Thread names and locals rely on dictionary/object traversal.
  • thread names via threading._active: src/python_threading.rs:19-81
  • locals via get_locals(): src/stack_trace.rs:289-327
  • dict/object formatting: src/python_data_access.rs:144-470
• Core dumps have their own dispatch table and currently always route Python
  3.14 through v3_14_0::_is.
  • src/coredump.rs:188-341

This architecture works well when the target CPython layout is known at compile
time. CPython 3.14t is a poorer fit because free-threaded builds have layout
differences from ordinary 3.14 while sharing the same Python language version.

Why 3.14t currently needs special handling

1. libpython name

Free-threaded CPython loads libpython3.14t.so*, while the existing Linux and
macOS is_python_lib() regex historically only accepted suffixes such as
m, d, and u.

Without recognizing t, py-spy can fail before it even reads Py_Version or
_PyRuntime.

Planned fix:

• Accept t in Linux/FreeBSD/macOS libpython matching.
• Add unit tests for libpython3.14t.so.1.0.
• Add Windows review item for possible python314t.dll naming if free-threaded
  Windows builds use a t suffix.

Relevant path:

• src/python_process_info.rs:854-878

2. free-threaded runtime detection

CPython 3.13+ exposes _PyRuntime.debug_offsets. The generated bindings
already include _Py_DebugOffsets for 3.13 and 3.14. Important fields include:

• free_threaded
• interpreter_state.threads_head
• interpreter_state.imports_modules
• thread_state.current_frame
• thread_state.thread_id
• thread_state.native_thread_id
• interpreter_frame.executable
• interpreter_frame.previous
• interpreter_frame.instr_ptr
• interpreter_frame.localsplus
• interpreter_frame.owner
• code_object.filename
• code_object.name
• code_object.qualname
• code_object.linetable
• code_object.firstlineno
• code_object.argcount
• code_object.localsplusnames
• code_object.localspluskinds
• code_object.co_code_adaptive
• pyobject.ob_type
• type_object.tp_name
• type_object.tp_flags
• tuple_object.ob_item
• tuple_object.ob_size
• list_object.ob_item
• list_object.ob_size
• dict_object.ma_keys
• dict_object.ma_values
• long_object.lv_tag
• long_object.ob_digit
• bytes_object.ob_size
• bytes_object.ob_sval
• unicode_object.state
• unicode_object.length
• unicode_object.asciiobject_size

The current local prototype only uses _Py_DebugOffsets.free_threaded as a
boolean discriminator. A complete upstream design should use debug offsets as
the main source of truth for CPython 3.13+ dynamic fields, not only as a flag.

Relevant paths:

• _Py_DebugOffsets in generated 3.14 bindings:
  src/python_bindings/v3_14_0.rs:4339-4528
• _Py_DebugOffsets in generated 3.13 bindings:
  src/python_bindings/v3_13_0.rs:13514-13666
• current prototype free-threaded detection:
  src/python_process_info.rs:396-431

3. PyObject and string layout

CPython 3.14t changes the PyObject / PyVarObject header layout. The
ordinary v3_14_0::PyUnicodeObject and v3_14_0::PyBytesObject layouts cannot
be blindly reused for 3.14t string and line-table reads.

This affects:

• filenames
• function names / qualified names
• line tables
• type names
• locals and repr formatting
• thread-name lookup through dictionaries

Relevant paths:

• string and bytes copying: src/python_data_access.rs:12-64
• current 3.14t minimal layout prototype:
  src/python_interpreters_3_14t.rs:87-107,
  src/python_interpreters_3_14t.rs:298-330

4. _PyStackRef tag bits

CPython 3.14 stores _PyInterpreterFrame.f_executable as _PyStackRef, not a
plain PyCodeObject *.

When converting a _PyStackRef that is expected to hold an object reference
back to a PyObject *, distinguish two concepts:

• the set of low-bit values CPython uses to validate or classify stackrefs;
• the bit(s) CPython actually masks when converting an object stackref to a
  PyObject *.

The 10.2 CPython 3.14.6 headers show:

• ordinary 3.14 non-debug, non-Py_GIL_DISABLED path:
  Py_TAG_BITS = 3 is used for validation/classification, while
  PyStackRef_AsPyObjectBorrow() masks only Py_TAG_REFCNT (1) through
  BITS_TO_PTR_MASKED;
• free-threaded 3.14t with Py_GIL_DISABLED=1:
  Py_TAG_BITS = 1, and PyStackRef_AsPyObjectBorrow() masks that bit;
• Py_INT_TAG = 3 exists in both branches for tagged integers.

This affects the code object pointer and lasti computation.

Do not hard-code a universal bits & !3 rule for every 3.14 object
stackref. A robust decoder should reject/null-skip unexpected null or
tagged-int f_executable values, then apply the build-appropriate object
pointer conversion. For the observed ordinary 3.14 and free-threaded 3.14t
non-debug builds, object stackref conversion masks bit 0.

The current 10.2 evidence is:

• /opt/python314/bin/python3: Py_GIL_DISABLED=0, ordinary GIL build.
• /opt/python314t/bin/python3: Py_GIL_DISABLED=1, free-threading build.

Relevant paths:

• ordinary 3.14 frame implementation:
  src/python_interpreters.rs:477-493
• current helper in prototype:
  src/python_interpreters.rs:115-117
• current 3.14t frame implementation:
  src/python_interpreters_3_14t.rs:172-191

5. GIL ownership semantics

Basic sampling should not require a GIL owner. However, --gil must not output
misleading data on a no-GIL runtime.

For complete behavior:

• If the target is an ordinary GIL build, preserve existing --gil behavior.
• If the target is a free-threaded build but runtime GIL is enabled, attempt to
  read the GIL owner via debug-offset fields and test this explicitly.
• If the target is a free-threaded build with runtime GIL disabled, make
  --gil fail clearly, for example:
  --gil is not supported when the target Python runtime has no active GIL.
• In non---gil modes, failure to read GIL ownership should not block stack
  sampling; it should set owns_gil=false or unknown, depending on whether
  the maintainer wants to represent unknown separately.

Relevant paths:

• PythonSpy::_get_stack_traces() GIL owner lookup:
  src/python_spy.rs:241-254
• generic get_stack_traces() GIL owner lookup:
  src/stack_trace.rs:82-89
• get_gil_threadid(): src/stack_trace.rs:329-355

Proposed design

A. Introduce a CPython runtime layout descriptor

Add a small internal descriptor for CPython 3.13+ debug offsets, for example:

pub struct RuntimeLayout {
    pub version: Version,
    pub free_threaded: bool,
    pub stackref_tag_bits: usize,
    pub interpreter_state: InterpreterStateOffsets,
    pub thread_state: ThreadStateOffsets,
    pub interpreter_frame: InterpreterFrameOffsets,
    pub code_object: CodeObjectOffsets,
    pub pyobject: PyObjectOffsets,
    pub type_object: TypeObjectOffsets,
    pub tuple_object: TupleObjectOffsets,
    pub list_object: ListObjectOffsets,
    pub dict_object: DictObjectOffsets,
    pub long_object: LongObjectOffsets,
    pub bytes_object: BytesObjectOffsets,
    pub unicode_object: UnicodeObjectOffsets,
}

This descriptor should be read once in PythonSpy::new() after version
detection and before stack dispatch.

For 3.13 and 3.14:

• read _PyRuntime;
• copy _Py_DebugOffsets;
• validate the cookie/version if practical;
• map offsets into RuntimeLayout;
• store it in PythonSpy.

For pre-3.13:

• keep the current compile-time trait implementation.

This keeps the large migration limited to CPython 3.13+ and avoids refactoring
older stable paths.

B. Add runtime-backed 3.13/3.14 interpreter access

There are two possible implementation styles.

Option 1: Minimal 3.14t-only adapter

Keep the current local prototype style:

• add python_interpreters_3_14t.rs;
• define minimal free-threaded structs by hand;
• dispatch Python 3.14t to this adapter;
• leave ordinary 3.13/3.14 on generated bindgen layouts.

Pros:

• small immediate diff;
• easy to prove record and dump are restored;
• lower risk for older versions.

Cons:

• hard-coded offsets make the review burden high;
• thread names, locals, dict traversal, and core dump support remain awkward;
• less future-proof for 3.15t or debug-offset changes;
• duplicated logic between static and runtime layouts.

Option 2: Runtime-offset adapter for 3.13+

Introduce a RuntimeInterpreterState path backed by RuntimeLayout.

This can be done without rewriting all versions:

• keep existing InterpreterState trait for pre-3.13 and current static paths;
• add a parallel runtime stack walker for 3.13+ using direct remote reads plus
  offsets;
• or incrementally modify trait methods to receive a RuntimeLayout.

Recommended for complete support:

• use a dedicated runtime-backed walker for 3.13+ first;
• keep old trait dispatch untouched for pre-3.13;
• after it is stable, consider replacing static 3.13/3.14 paths with the
  runtime-backed path to reduce duplicated maintenance.

Pros:

• aligns with CPython's debug-offset intent;
• avoids hand-coded struct padding;
• easier to extend to 3.15t;
• easier to explain to maintainer.

Cons:

• larger PR;
• touches stack walking and object access design;
• needs more tests.

C. Split core features by capability

Complete support should be built as layered capabilities, not as one monolithic
patch.

Capability 1: process discovery and runtime detection

Changes:

• recognize libpython3.14t.so*;
• detect free_threaded through _Py_DebugOffsets;
• record debug-offset availability in PythonSpy;
• add clear logs: detected version, free-threaded flag, runtime layout source.

Validation:

• unit test for is_python_lib();
• attach to /opt/python314t/bin/python3;
• verify version detection and _PyRuntime debug-offset read.

Capability 2: basic stack sampling

Changes:

• implement 3.14t frame walk;
• decode _PyStackRef with correct tag bits;
• read PyThreadState.current_frame;
• read PyThreadState.thread_id / native_thread_id;
• read PyCodeObject.filename/name/qualname/linetable;
• read PyUnicodeObject and PyBytesObject through free-threaded-aware offsets;
• skip frames whose f_executable is not a code object;
• treat both CPython 3.14 frame-owner boundary values as entry/shim frames.
  In the 10.2 CPython 3.14.6 headers these are
  FRAME_OWNED_BY_INTERPRETER = 3 and FRAME_OWNED_BY_CSTACK = 4;
• preserve ordinary 3.14 behavior.

Validation:

• record -f raw -d 60 on 3.14t, assert Samples > 0, Errors: 0,
  and profile contains busy_loop;
• dump on 3.14t, assert it contains busy_loop;
• top with a PTY, assert live sampling renders Python frames;
• ordinary GIL regression:
  • Python 3.12 record;
  • Python 3.13 record;
  • Python 3.14 record.

Capability 3: Unicode and line-number correctness

Changes:

• support ASCII and non-ASCII compact Unicode for 3.14t;
• support kind=1/2/4 string data;
• read linetable through bytes_object offsets;
• ensure line-number decoding still matches 3.14 line-table format.

Validation:

• file path with non-ASCII characters;
• non-ASCII function name;
• recursive stack;
• negative line-number offset test;
• compare dump and raw profile against expected function and line ranges.

Existing tests to adapt:

• tests/scripts/unicode💩.py
• tests/scripts/cyrillic.py
• tests/scripts/negative_linenumber_offsets.py

Capability 4: no-GIL GIL semantics

Changes:

• represent GIL owner as optional:
  • Some(thread_id) for known GIL owner;
  • None for no active/available GIL owner;
• make --gil explicitly unsupported when no GIL owner can exist;
• optionally read gil_runtime_state_enabled, gil_runtime_state_locked, and
  gil_runtime_state_holder through debug offsets when a free-threaded runtime
  has GIL enabled.

Validation:

• 3.14t no-GIL: normal record/dump succeeds;
• 3.14t no-GIL: record --gil fails with a clear error;
• ordinary 3.13/3.14: --gil behavior is unchanged.

Capability 5: thread names

Changes:

• do not enable thread-name lookup for 3.14t until dictionary traversal is
  proven safe;
• use interpreter_state.imports_modules from debug offsets;
• use free-threaded-safe object/type/string/dict traversal;
• audit DictIterator::from_managed_dict() because it already contains a TODO:
  MANAGED_DICT_OFFSET is -3 if GIL isn't disabled, -1 otherwise.

Risks:

• threading._active lookup depends on module dict, ordinary dict, thread
  object dict or managed dict, integer keys, and string values.
• Current DictIterator still relies on static PyDictKeysObject and
  PyDictUnicodeEntry layouts.

Validation:

• adapt test_thread_names to run on 3.14t;
• include multiple custom named threads;
• verify all expected names are present;
• run repeated sampling while threads are created/destroyed.

Relevant paths:

• src/python_threading.rs:19-81
• src/python_data_access.rs:144-343

Capability 6: locals and object repr

Changes:

• do not claim dump --locals support until localsplus and stackref object
  reads are correct for 3.14t;
• read interpreter_frame.localsplus through debug offsets;
• decode each local value as _PyStackRef, including tag handling;
• read local names from code_object.localsplusnames;
• handle strings, ints, bools, None, lists, tuples, dicts, floats, and unknown
  object fallback through free-threaded-aware object/type offsets.

Risks:

• Current get_locals() computes local address as
  frameptr + size_of_val(frame) - ptr_size, which is not a robust 3.14t
  strategy.
• Current 3.14t prototype returns nlocals() == 0, explicitly avoiding locals.
• Current format_variable() recursively depends on object layouts and dict
  layouts.

Validation:

• adapt test_local_vars;
• add free-threaded specific coverage for:
  • strings including non-ASCII;
  • None/True/False;
  • small integers;
  • lists/tuples/dicts;
  • empty strings;
  • nested containers;
  • long repr truncation.

Relevant paths:

• src/stack_trace.rs:289-327
• src/python_data_access.rs:355-470

Capability 7: native stack merge

Changes:

• basic native unwinding itself is mostly remoteprocess/unwinder behavior;
• py-spy-specific risk is merging native eval frames with Python frames;
• ensure is_entry / is_shim_entry markers are correct for 3.14t frame owner
  values. For CPython 3.14, do not rely on only one owner value; treat both
  FRAME_OWNED_BY_INTERPRETER and FRAME_OWNED_BY_CSTACK as boundary frames.

Risks:

• If 3.14t owner semantics differ, native/Python merge can over- or
  under-consume Python frames.

Validation:

• record --native on ordinary 3.12, 3.13, 3.14, and 3.14t;
• workload that calls a native extension or stdlib C function;
• verify nonzero samples, low error count, and no merge mismatch errors.

Relevant paths:

• native merge: src/native_stack_trace.rs:46-150
• Python frame is_entry: src/python_interpreters.rs:489-493 and
  3.14t equivalent.

Capability 8: core dump support

Changes:

• make PythonCoreDump detect free-threaded runtime via debug offsets;
• dispatch 3.14t core dumps to the same runtime-backed path used by live
  process sampling;
• decide whether thread names and locals are supported for 3.14t core dumps
  only after Capabilities 5 and 6 are proven.

Risks:

• Core dump map parsing is separate from live process map parsing.
• Core dumps cannot call into OS process APIs; all debug-offset data must be
  available in the dumped memory.

Validation:

• generate a 3.14t core dump from a busy loop;
• run py-spy dump --core;
• assert stack contains expected frames;
• test JSON output if --json is supported for core dumps.

Relevant path:

• src/coredump.rs:188-341

Proposed PR split

Do not submit all capabilities as one PR unless the maintainer explicitly asks
for it. A safer upstream path is:

PR 1: Recognize 3.14t and restore basic stack sampling

Scope:

• recognize libpython3.14t.so*;
• detect free-threaded runtime;
• add basic 3.14t frame/string/bytes/code support;
• non---gil record/dump/top work;
• --gil fails clearly for no-GIL targets;
• ordinary 3.12/3.13/3.14 basic record regressions.

Do not include:

• thread names;
• locals;
• native stack merge changes beyond what is required for non-native record;
• core dumps.

Why this PR is valuable:

• It turns py-spy from "cannot attach / cannot sample" into "basic production
  profiling works" for CPython 3.14t.

PR 2: Runtime-offset descriptor for 3.13+

Scope:

• introduce a reusable _Py_DebugOffsets descriptor;
• remove or minimize hard-coded 3.14t padding;
• optionally route ordinary 3.13/3.14 through the descriptor after regression
  testing.

Why separate:

• It is architectural.
• It should be reviewed independently from restoring basic user functionality.

PR 3: Unicode/line-number hardening

Scope:

• non-ASCII filenames and function names;
• full kind=1/2/4 Unicode coverage;
• line table coverage across ordinary 3.14 and 3.14t.

PR 4: thread names

Scope:

• free-threaded-safe dict/module traversal sufficient for threading._active;
• add 3.14t thread-name tests.

PR 5: locals and repr

Scope:

• _PyStackRef localsplus decoding;
• free-threaded object formatting;
• adapt test_local_vars.

PR 6: native and core dump support

Scope:

• native stack merge validation;
• core dump dispatch to runtime-backed 3.14t path;
• final documentation update for support matrix.

Recommended first PR wording

Suggested title:

Add basic profiling support for CPython 3.14 free-threaded builds

Suggested description:

This restores basic record/dump/top functionality for CPython 3.14t
free-threaded targets.

The change recognizes libpython3.14t, detects free-threaded builds via
_PyRuntime.debug_offsets.free_threaded, decodes the 3.14t interpreter frame,
code object, Unicode, and bytes layouts needed for Python stack sampling, and
keeps --gil from reporting misleading results when no GIL owner exists.

Out of scope for this first PR:

- --gil support on no-GIL runtimes
- thread names
- dump --locals
- native stack merge guarantees
- core dumps
- full subinterpreter semantics

Validation:

- cargo fmt --check
- cargo test --lib
- CPython 3.14t record -f raw -d 60: Samples > 0, Errors: 0
- CPython 3.14t dump: stack contains busy_loop
- CPython 3.14t --gil: fails clearly
- ordinary CPython 3.12/3.13/3.14 record regressions

Validation matrix for author review

Local Rust checks

cargo fmt --check
cargo test --lib
cargo test --release

Existing integration tests

Run against ordinary GIL Python before and after changes:

python tests/integration_test.py
cargo test --test integration_test

At minimum cover:

• Python 3.12
• Python 3.13
• Python 3.14 ordinary GIL

3.14t live-process tests

For /opt/python314t/bin/python3 or an equivalent free-threaded build:

py-spy record -f raw -d 60 -o profile.raw -- python314t busy.py
py-spy dump -p <pid>
py-spy top -p <pid>   # with a real TTY
py-spy record --gil -f raw -d 2 -o gil.raw -- python314t busy.py

Expected:

• normal record succeeds;
• raw profile contains busy_loop;
• sample count is nonzero;
• error count is zero;
• dump contains expected Python frames;
• --gil fails clearly for a no-GIL runtime.

Unicode tests

Use workloads equivalent to:

• tests/scripts/unicode💩.py
• tests/scripts/cyrillic.py

Expected:

• filename and function names are not corrupted;
• raw and dump output remain UTF-8 valid.

Threading tests

Before thread-name support:

• multi-threaded stack sampling must not crash;
• thread names may be None.

After thread-name support:

• tests/scripts/thread_names.py equivalent should pass on 3.14t.

Locals tests

Before locals support:

• dump --locals on 3.14t should fail clearly or be documented as unsupported.

After locals support:

• tests/scripts/local_vars.py equivalent should pass on 3.14t.

Native tests

After native support is claimed:

• record --native on 3.14t should complete with nonzero samples;
• native/Python frame merge should not report mismatch errors;
• ordinary 3.12/3.13/3.14 native regressions should still pass.

Core dump tests

After core support is claimed:

• create a 3.14t core dump from a busy loop;
• run py-spy dump --core;
• verify stack output contains expected frames.

Current local prototype status

The current local prototype in /home/honglei/bwh/py-spy-issue711 is useful as
evidence for PR 1 only. It has passed:

• local cargo fmt --check;
• local cargo test --lib;
• 10.2 cargo +stable build --release;
• 10.2 cargo +stable test --lib;
• 10.2 CPython 3.14t 60-second record -f raw: Samples: 5999 Errors: 0;
• 10.2 CPython 3.14t dump: stack contains busy_loop;
• 10.2 CPython 3.14t --gil: fails with failed to get gil_thread_id;
• 10.2 ordinary CPython 3.14 record: Samples: 5999 Errors: 0;
• 10.2 ordinary CPython 3.13 record: Samples: 5999 Errors: 0.

It still needs at least a 3.12 live regression before even the basic PR can
claim 3.12/3.13/3.14 ordinary GIL coverage.

It does not yet prove:

• thread names;
• locals;
• native stack merge;
• core dump support;
• subinterpreter correctness;
• full free-threaded GIL-state handling.

It also exposed two implementation follow-ups before PR extraction:

• ordinary 3.14 and 3.14t is_entry() should accept both owner boundary values
  observed in CPython 3.14 headers (3 and 4), not only one value;
• stackref decoding should reject/null-skip unexpected null or tagged-int
  f_executable values and avoid treating bits & !3 as a universal object
  pointer conversion rule.

Author-review questions

1. Is a minimal 3.14t adapter acceptable for a first PR, or would the project
   prefer a runtime-offset descriptor first?
2. Should non---gil modes treat missing GIL owner as owns_gil=false, or
   should the data model distinguish unknown from false?
3. Should --gil on a no-GIL runtime fail at argument/runtime validation time
   with a dedicated error message instead of surfacing a low-level memory read
   error?
4. Should dump --locals on 3.14t be explicitly rejected until localsplus and
   free-threaded object formatting are implemented?
5. Does the maintainer want 3.14t core dump support in the first free-threaded
   PR, or is live-process support enough for the initial merge?

Recommended next step

Before submitting anything, convert the current prototype into a smaller PR 1:

• include only process discovery, free-threaded detection, basic stack walking,
  Unicode/bytes support needed for filenames/function names/line tables, and
  clear no-GIL --gil behavior;
• add a 3.12 live regression run to the current evidence;
• keep thread names, locals, native, and core dump work out of PR 1;
• mention the runtime-offset descriptor as the intended follow-up path.

[honglei]

I started implementing the first, lowest-risk slice of the plan: basic stack sampling for CPython 3.14 free-threaded builds.

Scope of this first PR:

• recognize Linux/macOS libpython3.14t shared libraries
• detect CPython 3.14 free-threaded builds through _PyRuntime.debug_offsets.free_threaded
• add a minimal 3.14t interpreter layout for basic stack walking, code object names, filenames, and line numbers
• keep thread names, locals, native stack, memory profiling, core dumps, and subinterpreter coverage out of scope for this PR
• reject --gil explicitly on free-threaded builds instead of reporting a low-level GIL-state read failure

Validation completed before submitting the PR:

• local cargo fmt --check
• local cargo test --lib: 14 passed
• local cargo test --release: lib/main/integration/doc tests passed
• remote Linux x86_64 CPython 3.14t 60s record -f raw: Samples: 5999 Errors: 0
• remote Linux x86_64 CPython 3.14t dump: captured the expected busy_loop frame
• remote Linux x86_64 CPython 3.14t record --gil: fails clearly with --gil is not supported for free-threaded Python builds
• remote Linux x86_64 ordinary GIL regressions:
  • CPython 3.14: 60s record -f raw, Samples: 5999 Errors: 0
  • CPython 3.13: 60s record -f raw, Samples: 5999 Errors: 0
  • CPython 3.12: 60s record -f raw, Samples: 5999 Errors: 0

This work was prepared with assistance from Codex / GPT-5.5, with the implementation and validation results checked against local and remote test runs before submission.

[honglei]

Opened the first scoped PR here:

• Add basic profiling support for CPython 3.14 free-threaded builds #860

This PR covers basic CPython 3.14t stack sampling only. It references this issue and includes the local/remote validation evidence listed above. The work was prepared with assistance from Codex / GPT-5.5, with validation run before submission.