Skip to content

refactor(platform_compat): carve the lower layers into owner modules - #21000

Merged
bolichen97 merged 1 commit into
mainfrom
refactor/linecap-s03-platform-compat
Oct 18, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
refactor/linecap-s03-platform-compat

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: src/kiro_crew/platform_compat.py moves its lower layers, unchanged, into twelve focused owner modules, with every import path, patch target and behaviour kept, as the first of two steps that bring it under the 2,000-line cap.

platform_compat.py is 11,211 lines. Kiro Crew is adopting a hard rule that no hand-written file exceeds 2,000 lines (#20192), and this file changes about 14 times a week. Moving it in one PR would make a diff of about 1.05 MB, past the 1 MB cap the Design, UX and Security Scope review lanes enforce. So the move is split into two stacked PRs of at most 900 KB each. This PR moves everything above the file-permission helpers, plus the /proc readers and the process alarm and clocks that code reads.

Why it matters

Every POSIX call in the codebase routes through this one module, so it is where cross-platform bugs are fixed, and an 11k-line file buries each fix among unrelated platforms and process families. Every feature PR that touches it also trips the line-cap guard. Splitting it mechanically keeps feature work unblocked and makes each family — the macOS process table, liveness, identity, ports, the Windows process trees, termination — reviewable on its own.

Not a goal

  • No behaviour change: no probe, refusal, message, log line, timeout or default changes. Every moved unit is byte-identical except comment and docstring wording the added-line gates require.
  • Not the second half: the file-permission, link and no-reparse helpers, the process and host metrics, the Windows Job object helpers and the remaining runtime helpers move in PR 2.
  • No new behaviour test, and no change to kiro_crew._facade_mirror (refactor: add a mirror-aware facade helper for module splits #20337).

What changed (motivation → approach → change)

platform_compat.py already forwarded the file locks and the owner-only helpers to two modules, but those owners read the platform flags and lock modules back from it at call time, and no owner could import another. Its code is one reference graph, and tests patch names it only imports (IS_WINDOWS at 757 sites, time, ctypes, sys). So any split that keeps the code unchanged needs owners that import each other, plus a facade whose patches reach every owner. That is the campaign's shared mirror, kiro_crew._facade_mirror, as sandbox.py already uses it.

Owner Responsibility Lines
platform_compat_native.py platform flags, signal and process-creation constants, Win32 struct layouts, the query-only process handle 288
platform_compat_proctable.py the kernel's process table: macOS libproc/sysctl, Linux /proc, file holders and flock owners 1,480
platform_compat_runtime.py UTF-8 environment and console, re-exec and exit seams, process alarm and clocks, bundled interpreter, isolated argv 616
platform_compat_files.py the no-replace rename and directory publication, TCC walk pruning 356
platform_compat_trust.py trusted system binaries, env allowlist, Known Folders, path trust, reveal and open 978
platform_compat_liveness.py pid liveness, thread-group leaders, zombies, process groups, thread count 291
platform_compat_identity.py parent, image, command line, start identity and time, owner uid, namespaces, cgroups, sandbox, argv match 1,053
platform_compat_ports.py TCP peer pid, listeners on a port 692
platform_compat_descendants.py descendant walks, parent maps, Toolhelp bounds 704
platform_compat_winproc.py exact Windows process handles, a tree's descendant handles (sync and async) 540
platform_compat_wintree.py the Windows process trees the gateway owns 676
platform_compat_kill.py signalling and reaping; every os.killpg / kill_pid / kill_process_tree call, pgroup_exists included, because the kill-chokepoint ratchet exempts this one file 638

How the facade works:

  • Each unit moved whole, with the comment block above it, by a reproducible recipe. Owners import only lower owners, never the facade, and log as logging.getLogger("kiro_crew.platform_compat") (L25).
  • The owners are top-level platform_compat_<role>.py siblings, not a package. The Cross-Platform Portability gate excludes them by name with one added pathspec row, :(exclude)src/kiro_crew/platform_compat_*.py, beside its platform_compat.py exclude, so the moved POSIX primitives stay unscanned as they were. Its src/kiro_crew/**/*.py pathspec matches no top-level module today either (cross-platform gate never scans top-level src/kiro_crew modules (pathspec '**' needs a sub-directory) #21019). The owning spec records this.
  • platform_compat.py (11,216 -> 3,722 lines on main) keeps its BASE imports (# noqa: F401 where its own code no longer reads one), binds the moved names its remaining code reads one per line (# noqa: E402), and installs _facade_mirror.install(..., excluded=(), forwards=<the lock and owner-only table>). A write through the facade lands on every carved owner that binds the same object; the lock and owner-only modules keep their single-owner forwarding.
  • It also binds the platform flags, the three names the lock and owner-only modules read from it, kill_pid (patched with unpacked keyword arguments) and the three helpers test_skill_discover reads from vars(platform_compat).
  • test/facade_mirror_scan.py, which the mirror guards use to find every test that patches through a mirrored facade, answers its per-file mention test from one pass over each text instead of one regex per spelling. platform_compat adds 283 spellings, and the old scan pushed the census past CI's 120 s per-test timeout; the new one selects exactly the same files (Master grant). Only plain module names (dotted ASCII identifiers) take that path; any other name still runs main's patterns, and main's alias-of-parent check (_alias_chain, test: route alias-of-parent facade patches to the syntax tree (#21652) #21786) applies on both paths.

Backwards compatibility

Compatible: every name kiro_crew.platform_compat bound at BASE still resolves to the same object (test/campaign_facade_inventories/kiro_crew.platform_compat.json freezes its 222 names for test_campaign_facades_base_public_names), __all__ is identical (279 names), and every patch through the facade still reaches every reader (test_facade_mirror_guards, test_platform_compat_refactor_facade).

Each public def this PR moves stays importable from kiro_crew.platform_compat (served or bound by the facade). One line per owner names all 128 of them:

Reader: src/kiro_crew/platform_compat.py:darwin_child_pids,darwin_established_tcp_count,darwin_footprint_tree_mb,darwin_kinfo_proc,darwin_libproc_available,darwin_pgroup_members,darwin_pid_is_zombie,darwin_process_argv,darwin_process_environ,darwin_process_facts,darwin_process_path,flock_owner_pid,linux_pgroup_members,parent_pid,pids_holding_file,proc_child_map,proc_cpu_jiffies_for_pids,proc_phys_footprint_bytes_for_pid,read_proc_stat,read_proc_status_int -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_proctable and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:arm_process_alarm,awake_now,boottime_now,cancel_wheel_applies_in_flight,ensure_line_buffered_stdout,ensure_utf8_console,execv_target_available,exit_after_failed_restart_exec,hard_exit,is_bundled_interpreter,is_windows_on_arm,isolated_python_argv,keep_for_reexec,kept_for_reexec,process_age_secs,process_alarm_available,process_start_boot_secs,reexec_launcher,reexec_python_module -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_runtime and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:publish_dir_noreplace,rename_noreplace,tcc_protected_dirs_for_walk,tcc_prune_walk_dirs -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_files and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:aws_bin_declined_on_ownership,env_key_allowed,group_write_admits_another_account,open_with_default_app,reveal_in_file_manager,short_path_name,tool_outside_trusted_dirs,traversed_components,traversed_components_and_links,trusted_aws_bin,trusted_git_bin,trusted_system_bin,trusted_system_bin_quiet,trusted_system_path,windows_documents_dir,windows_powershell_profile_paths -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_trust and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:is_thread_group_leader,live_thread_group_leaders,pgroup_of,pgroup_of_leader,pid_exists,pid_is_zombie,pid_liveness,process_thread_count -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_liveness and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:effective_uid,get_ppid,get_process_start_id,get_process_start_identity,is_exec_supervisor_of_this_process,linux_process_name,own_process_start_time,process_argv_fingerprint,process_argv_matches_exact,process_can_read_under_sandbox,process_cgroups_match,process_command_line,process_cwd,process_executable_path,process_image_name,process_incarnation_id,process_is_sandboxed,process_matches,process_namespaces_match,process_owner_uid,process_start_id_for_source,process_start_time -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_identity and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:address_covers_loopback,find_listening_pids,find_port_listeners,get_tcp_peer_pid,listening_pid_tool,listening_pid_tool_available,loopback_owner_pids,probe_port_listeners,process_owns_loopback_listener -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_ports and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:attributed_descendants,created_after,process_descendant_identities,process_descendants -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_descendants and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:close_process_handle,descendant_termination_handles,descendant_termination_handles_async,duplicate_asyncio_process_handle,open_process_termination_handle -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_winproc and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:create_windows_cleanup_owned_process,finish_windows_cleanup_owned_spawn,process_handle_active,release_windows_tree_reservation,reserve_windows_tree_cleanup,retry_pending_windows_process_trees,terminate_process_handle,terminate_windows_asyncio_tree,terminate_windows_process_tree_owned -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_wintree and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)
Reader: src/kiro_crew/platform_compat.py:kill_and_reap,kill_pid,kill_pid_async,kill_pid_pinned,kill_popen_tree,kill_process_group,kill_process_tree,kill_process_tree_async,kill_process_tree_pinned,pgroup_exists,terminate_and_reap,terminate_and_reap_sync -- chat -- each is the same object at kiro_crew.platform_compat.<name>, defined in platform_compat_kill and served by the facade (test_campaign_facades_base_public_names, test_platform_compat_refactor_facade)

Tests

  • test/test_platform_compat_refactor_facade.py (Master grant): _CARVED merged into _OWNERS, _MOVED rows per owner, _BOUND_HERE passed to check_forwarded_and_bound_are_disjoint (the test is renamed to say so), a _CARVED_IMPORTS edge table passed to check_owner_dependency_direction, mirrored=/carved= on the two shared-bindings checks, and two parity tests: the mirror indexes exactly _CARVED_OWNERS with no divergence, and the lock and owner-only modules stay out of it.
  • test/campaign_facade_inventories/kiro_crew.platform_compat.json: the facade's frozen inventory (222 BASE public names and the 5 names it re-binds from other modules), which test_campaign_facades_base_public_names loads.
  • Path-only re-points (L30), each proved by a mutation the test catches:
    • test_kill_chokepoint_ratchet.py: PRIMITIVE_HOME is platform_compat_kill.py, which holds all ten exempt calls; the count stays 67;
    • test_spawn_audit.py (12 BENIGN_SPAWNS keys), test_windows_kill_probe_audit.py (2 GATED_PROBES keys), test_internal_python_isolation.py (1 row), test_jsonl_util.py (kernel pseudo-file rows); test_sel_hard_exit_flush.py's _PATHS, _EXEMPT key and restart-exec test read platform_compat_runtime.py, where hard_exit lives.
  • Joins (L40(8)): the two universal source pins that read the whole of platform_compat.py at BASE read the facade plus every platform_compat_*.py owner, by glob, with their assertions unchanged:
    • test_sel_hard_exit_flush.py _MODULES (every hard exit drains the audit queue): an undrained os._exit planted in the facade, or in platform_compat_wintree.py, turns it red;
    • test_docs_mock_pid_convention.py _public_kill_helpers() (every public kill/reap helper is named in the doc): a def kill_probe_x() planted in the facade, or in platform_compat_wintree.py, turns it red.
      Their docstrings name the family instead of the one file.
  • test/facade_mirror_scan.py (Master grant): _mentions reads each text once for its from ... import lists (_from_imports) and once per text and leaf for <parent>.<leaf> and relative spellings (_leaf_parts), and _Bindings looks spellings up by dotted prefix. Equivalence, old against new over the whole test tree (4,501 files, all four mirrored facades): 0 disagreements; the same 1,205 (file, spelling) mentions, the same 920-file family, and identical needs_syntax_tree, text-patched names, routed patch names and 57,967 patch events (sha256 digests in the move report). With CI's coverage flags and --timeout=120, the census takes 32 s, the namespace-write scan 14 s and the create_true scan 3 s run together (41 s, 37 s and 22 s each alone); with the old scan the census took about 155 s.
  • Rows: .github/file-line-cap-baseline.txt keeps main's platform_compat.py row as it is, because the file stays over the cap until the second step, which deletes the row; .github/subprocess-encoding-baseline.txt drops its platform_compat.py row (see below).

Local gate floor. The related set, mypy and semgrep ran on a tree that differs from this head only by the liveness module's summary line and the rebase onto main (git range-diff shows =); the tree scans, integration and wheel smoke ran one step earlier, before the six __module__ pins (whose own tests ran after them); the mirror guards, the line cap and the re-pointed pins re-ran at this head:

  • 630 related test files (run_scoped_tests backend set: every test that references a changed file): 48,320 passed, 0 failed, 5 xfailed;
  • 215 more tree-scanning test files outside that set, with CI's coverage flags and --timeout=120: 13,363 passed, 0 failed;
  • KIROCREW_INTEGRATION=1 pytest -n 2 test/integration: 62 passed, 1 failed, test_owner_only_boot.py::test_a_fresh_boot_leaves_nothing_readable_by_others, which fails the same way on main on this host (umask 022) and passes in CI;
  • mypy clean (2,442 files); flake8, isort and black clean; docs lint passed; flake-pattern ratchet passed; line-cap check 0 failures;
  • brand, comment-history and subprocess-encoding checks clean;
  • semgrep (CI configs) over every new and changed Python file: 0 results, 0 errors;
  • installed-wheel smoke: the wheel ships all twelve owners, and each imports from site-packages;
  • the diff measures 826,240 bytes against main, under the 900 KB cap (L27);
  • git diff and git diff --minimal add the same lines in every changed file (platform_compat.py: 514 each; test/facade_mirror_scan.py: 81 each).

scripts/local-gate.py --dry-run selects 630 backend and 363 frontend (cross-surface) files, past the 600-file local cap, so the floor above ran instead (SD14). No file under website/ changed.

The three subprocess.check_output(..., text=True) calls the encoding baseline counted (probe_port_listeners, process_command_line, process_owner_uid) carry the gate's # subprocess-encoding: locale marker with its reason (darwin ps and lsof write their output in the user's locale). The markers record a deliberate locale decode that matches BASE, and they replace the 3-count baseline row.

Manual verification

N/A — a pure move: the floor above, the move audit and the base-name and patch-reach contracts prove the behaviour is unchanged.

Move audit

src/kiro_crew/platform_compat.py: 11216 -> 3722 lines; moved 95.75% (python-ast)

Changed units (17, 417 lines), each glue or a gate-required wording edit:

  • the forwarding machinery replaced by the mirror (133 lines): _EXPORTS_BY_OWNER (now _FORWARDS_BY_OWNER plus a derived table), the TYPE_CHECKING manifest, _ReExportModule, _owner, _index_exports, if not TYPE_CHECKING: __getattr__, _EXPORTS, the class swap;
  • docstring wording the comment-history and brand gates require (284 lines): process_command_line ("Used to", "KiroCrew"), ensure_utf8_console ("KiroCrew"), process_matches, process_owner_uid, process_thread_count, parent_pid, address_covers_loopback ("Used to"), _darwin_process_cpu_nanos, _darwin_process_cwd ("no longer").

Outside the replaced machinery, 97.1% of the moved lines are byte-identical by AST. Comment-only edits (the encoding markers, three comments that name where code now lives, a brand fix in a comment) do not change the AST.

Observable difference (L24, reported to the Master): reading a forwarded lock or owner-only name through kiro_crew.platform_compat after a test deletes it from its owner raises AttributeError naming kiro_crew.platform_compat instead of the owner module. hasattr, getattr with a default, dir() and the unknown-name message are unchanged, and no test or caller reads that text.

Logger names (L25): every carved owner that logs uses logging.getLogger("kiro_crew.platform_compat"), the BASE logger, because tests and log filters read that name.

Class __module__: the six moved exception and enum classes (WindowsCleanupCapacityError, _WindowsTreeOverflow, WindowsTreeDrainPending, _DarwinLibprocUnavailable, ProcessIdentitySource, _ProcessStartOrder) keep __module__ == "kiro_crew.platform_compat", set right after each class, so tracebacks, logs and pickles render the BASE path; a test pins it and that the list is complete. Every other moved class keeps its owner's __module__: NamedTuple rows (their repr omits the module), the private ctypes structures and _PendingWindowsTreeCleanup, which nothing renders; no test, log or caller reads their module.

Prose citations (L29): docs/guides/windows-install.md (_ThreadEntry32 lives in platform_compat_native) and docs/system-specs/modules/app-kit-platform.md (platform_compat_wintree.py), and the BUNDLED_BACKEND_DIST_DIRNAME comment in src/kiro_crew/platform_compat_runtime.py, which names the test that pins it: test_platform_compat.py -> test/test_platform_compat_pinned_tools.py, where TestIsBundledInterpreter lives on main.

References not edited (cost, L50): website/electron/gateway-env.js:16 says platform_compat.py republishes the same invariant; the republish (_ensure_utf8_process_environment) is defined in src/kiro_crew/platform_compat_runtime.py and runs on import of kiro_crew.platform_compat.

CI path references

  • .github/workflows/macos-on-demand.yml: the darwin filter lists the twelve new owner files after src/kiro_crew/platform_compat.py. No logic change.
  • .github/workflows/ci.yml: the windows path filter lists 'src/kiro_crew/platform_compat_*.py' after src/kiro_crew/platform_compat.py, so a fork PR that edits the moved Windows code still runs Backend Tests (Windows). No logic change.
  • .github/workflows/cross-platform.yml: one pathspec row, ':(exclude)src/kiro_crew/platform_compat_*.py', after the platform_compat.py exclude, so the gate exempts the moved code as it exempted platform_compat.py. No logic change.

Related Issues

Part of #20192

Follow-up: #21320 (the comment citation listed under References not edited)

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license (see CONTRIBUTING.md).

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 15, 2026 23:35
@bolichen97
bolichen97 requested a review from CrysisDeu October 15, 2026 23:35
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 15, 2026
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Before merge, confirm the macOS on-demand and Windows lanes passed on this head. The moved Darwin and Win32 branches only run there, and the main CI does not run them.

[DESIGN-REVIEWED] c30ff5a

Description read

[DESCRIPTION-READ] 89c78ccd0f0c5e2e0a591484408133a1756c7e5d4021f1130261436358ec97da

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the claim that the rewritten test/facade_mirror_scan.py fast path "selects exactly the same files" as main's per-spelling regexes.

What this change ships

Inventory (8 items) — 8 justified

Intent: bring platform_compat.py toward the 2,000-line cap that AGENTS.md mandates, with no behaviour change. ADDITION (mechanical refactor).

  1. Lower layers of platform_compat.py move whole into twelve platform_compat_<role>.py owners — justified
  2. platform_compat facade keeps every BASE name, __all__, and patch reach via _facade_mirror — justified
  3. Mirror-scan census answers plain module names in one pass instead of one regex per spelling — justified
  4. Cross-platform and CI pathspecs exclude or cover platform_compat_*.py as they did the original file — justified
  5. macOS on-demand trigger list gains the twelve owners — justified
  6. Kill-chokepoint, spawn, exit, /proc and probe audit pins retargeted to the owning files — justified
  7. Subprocess-encoding baseline drops its platform_compat.py row — justified
  8. Spec and guide references renamed to the owners — justified

[FIRST-PRINCIPLES-REVIEWED] c30ff5a

Description read

[DESCRIPTION-READ] 3c84647b303adfc901d9fcc0248889726197e9aa9cb7d3c318fe071cc4308417

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c30ff5a

Verdict parsed from the review's SHA-scoped output markers for commit c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d.

False positive or not applicable? A repository writer can comment:
/ai-review override fable c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d: <one-sentence reason>

Comment thread src/kiro_crew/platform_compat_trust.py Dismissed
@github-actions

github-actions Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c30ff5a

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 16, 2026 00:05
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=81511f47466b Item 6: the three subprocess-encoding markers and the dropped baseline row

rebutted: the description declares it. Under ## Tests it names the three subprocess.check_output(..., text=True) calls the baseline counted (probe_port_listeners, process_command_line, process_owner_uid) and says they carry the gate's own # subprocess-encoding: locale marker; the Rows bullet says the baseline drops its platform_compat.py row.
The marker is the gate's documented opt-out for a deliberate locale decode. It is a comment, so the bytes each call decodes, and how, are unchanged, which is this PR's no-behaviour-change goal.
No other spelling keeps both the behaviour and the gate: encoding="utf-8" changes the decode, the baseline is shrink-only so the new paths cannot get rows, and a row left for platform_compat.py is a stale row the gate rejects.
The campaign maintainer ruled this marker for these three moved calls before the PR opened.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Answers to the two whole-design punchlines on bda3e1567e1252661d19ec416f7e24d31e546c11:

First Principles: does the rewritten test/facade_mirror_scan.py pick exactly the same test files? Yes. Before this head, old and new scans were run side by side over the whole test tree (4,501 files, all four mirrored facades: acp.client, crew_log.projection, platform_compat, sandbox; 296 spellings and 52 owners). They gave 0 disagreements:

  • 185,495 (file, name) mention probes compared, with the same 1,205 hits (identical sha256);
  • the same 920-file family selection;
  • identical needs_syntax_tree, text-patched names, routed patch names (527) and patch events (57,967 over 920 files), each by sha256 digest.

An independent review re-checked it on 1,566,348 real pairs, 108 hand-written edge cases (relative imports, aliases, nested patch strings, multi-line from-imports) and 200,000 fuzz texts, also with 0 disagreements.

Design: do the Windows and macOS shards pass? Windows does: Backend Tests (Windows) 1-8, Backend Tests (IPv6, windows-latest), E2E Gateway Boot (windows-latest), Pod Boot Canary (Windows) and Windows Fail-Closed Sandbox Contract are all green on this head. The on-demand macOS suite matched this diff's darwin paths, but it was skipped on the pool cap ("at least 4 live lane run(s) already hold the macOS pool"). It needs ci:macos or a re-dispatch, which I have asked a maintainer for.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=546d0d71f553 Explicit cross-platform exclude for the platform_compat_ owners*

rebutted for this head: nothing is scanned differently today. cross-platform.yml's 'src/kiro_crew/**/*.py' (default pathspec magic) matches no module directly under src/kiro_crew/, so before and after this PR the moved POSIX primitives sit outside the scan, as platform_compat.py did through its named exclude. The owning spec, docs/system-specs/common/platform-compat.md, records that the owners rely on this.
The disagreement between the gate's header comment and its behaviour is filed as #21019, which notes that any fix needs the owners' exclude alongside it.
The explicit :(exclude)src/kiro_crew/platform_compat_*.py row, a path-list row naming this split's parts, lands with the next push this PR needs anyway; it is not worth a CI round on its own (maintainer ruling).

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in .github/subprocess-encoding-baseline.txt, .github/workflows/macos-on-demand.yml, test/test_spawn_audit.py, test/test_kill_chokepoint_ratchet.py, docs/system-specs/common/platform-compat.md, docs/system-specs/modules/app-kit-platform.md and test/facade_mirror_scan.py since bda3e1567e went green (93617e9 -> 0ad64e6); CI re-running on 761f6f6899.

This head also carries:

The moved code is unchanged from bda3e1567e.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 16, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Answers to the whole-design punchlines on 761f6f689943400d3cf44bcf0256a3b45f017d90:

Design: are the Windows and macOS lanes green? Yes. On this head these all pass:

  • Backend Tests (Windows) 1-8;
  • macOS Tests / Backend Tests (macOS) 1-4 (ci:macos);
  • Pod Boot Canary (Windows);
  • Windows Fail-Closed Sandbox Contract;
  • Electron Shell Tests (Windows port identity).

First Principles: does the rewritten test/facade_mirror_scan.py matcher pick the same test files as the old regexes? Yes, as shown earlier in this thread. Run side by side over all 4,501 test-tree files and all four mirrored facades, the old and new scans had 0 disagreements: the same 1,205 mentions, the same 920-file family, and identical routed patch names and 57,967 patch events, compared by sha256. An independent review re-checked it on 1.57M real pairs, 108 hand-written edge cases and 200,000 fuzz texts. The test/facade_mirror_scan.py change on this head adds only the union with #20813's \b word-boundary fix in _text_aliases, which my rewrite does not touch.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 16, 2026
@bolichen97
bolichen97 force-pushed the refactor/linecap-s03-platform-compat branch from 761f6f6 to 7f106e2 Compare October 16, 2026 16:32
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main changed src/kiro_crew/platform_compat.py, which made this PR conflict. 61bd116 (#21159) added process_incarnation_id, so the base moved 0ad64e6 -> 32dddfc and CI is re-running on 7f106e2324.

The new function is ported unchanged into its owner, platform_compat_identity.py. It sits next to _own_identity_token and own_process_start_time, its neighbours on main. kiro_crew.platform_compat.process_incarnation_id, the name the new test patches, still reaches its reader. The facade's name inventory and the description's Reader: list include it. Nothing else changed in the moved code. This head supersedes 761f6f6899.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 16, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 18, 2026
@bolichen97
bolichen97 force-pushed the refactor/linecap-s03-platform-compat branch from e98cdb1 to 5cb8dc9 Compare October 18, 2026 11:25
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 18, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main changed test/facade_mirror_scan.py (#21786), which made this PR conflict. The base moved from 27ab938 to 924c159, and CI is re-running on 5cb8dc9d01.

  • Scan: main's _spelling_patterns, _mentions loop, _alias_chain and needs_syntax_tree are kept as they are on main. The faster per-text reading now applies only to plain module names (dotted ASCII identifiers), and every other name runs main's patterns. Over the whole test tree (5,210 files, 50 mirrored facades, 449,882 name/file pairs) the result equals main's scan exactly: the same files, routed names and patch events, compared by sha256.
  • platform_compat.py: fix(mcp): keep the policy for a long-path, relative or missing handler on another drive #20746 changed strip_extended_length_prefix. That code stays in the facade in this PR, and git merged it without conflict.
  • One comment cite: the comment above BUNDLED_BACKEND_DIST_DIRNAME in platform_compat_runtime.py now points at test/test_platform_compat_pinned_tools.py.

This head supersedes e98cdb1ce8.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 18, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • PASS punchline: the platform_compat_*.py exclude glob in cross-platform.yml

confirmed as intended: the glob is meant to cover every platform_compat_* module, these twelve and any later one. That prefix is the owner namespace of platform_compat.py, the module the AGENTS.md cross-platform rule routes POSIX calls into, and the BASE row already exempted that code by its file name.
docs/system-specs/common/platform-compat.md states it in the same commit: the gate excludes platform_compat.py and the platform_compat_*.py owners by name because they hold the POSIX primitives this layer exists to name. Every module outside the prefix stays scanned.
The campaign maintainer ruled the glob in on this PR's earlier head (span=546d0d71f553 asked for a gate-side exemption instead of an accident of glob matching).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • PASS punchline: no test pins that _mentions_plain selects the same files as main's patterns

rebutted with evidence: the equivalence was measured, not assumed. A replay ran main's _mentions and this head's over the whole test tree (5,210 files, 449,882 file-by-name pairs): both answered True on the same 5,921 pairs (identical digest), and the downstream selections match too: 3,068 patching files, 118,647 patch events, 765 syntax-tree reads, the routed patched names of all 50 facades. Zero disagreements.
A fuzz pass over generated names and texts found disagreements only for names that are not dotted identifiers; the plain-name gate sends those to main's unchanged pattern path, and the re-run shows 0 _mentions disagreements.
The scan is a test helper whose callers are the census guards; their non-vacuity self-tests (for example test_facade_mirror_guards.py, test_cron_service_bindings.py) fail when the scan stops finding the patches they know of. A standing old-vs-new comparison test would have to keep main's slow path as a second implementation, so the replay stays as review evidence rather than a gate.

platform_compat.py is 11,211 lines, far past the 2,000-line cap. This
first of two PRs moves its lower layers, unchanged, into twelve sibling
owner modules: the native flags and Win32 layouts, the kernel process
table, the interpreter and process image, the no-replace rename and TCC
pruning, path and binary trust, liveness, identity, ports, descendant
walks, Windows process handles, owned Windows trees, and termination.
platform_compat.py drops to 3,721 lines.

platform_compat.py stays the import and patch surface. It installs
kiro_crew._facade_mirror, so a patch through kiro_crew.platform_compat
reaches every carved owner that binds the name, as it reached the one
module before. The lock and owner-only modules keep their single-owner
forwarding. Every owner logs as kiro_crew.platform_compat.

The facade-mirror guards' corpus scan answers its per-file mention test
from one pass over each file's text instead of one regex per spelling,
so the census stays well inside the per-test timeout now that
platform_compat adds 283 spellings. It selects exactly what it selected
before.

Part of #20192
@bolichen97
bolichen97 force-pushed the refactor/linecap-s03-platform-compat branch from 5cb8dc9 to c30ff5a Compare October 18, 2026 20:14
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main changed docs/system-specs/modules/app-kit-platform.md (#21940), which made this PR conflict. The base moved from 924c159 to 8fd2af9, and CI is re-running on c30ff5a6a0.

The conflict was one cite line. Main renamed manager.py to manager_uninstall.py, and this PR renamed platform_compat.py to platform_compat_wintree.py on the line after it. Both edits are kept. The code diff is unchanged: the -U0 patch and the 30-path set equal those of 5cb8dc9d01, and the patch-id is the same. This head supersedes 5cb8dc9d01.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 18, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • PASS punchline: confirm the macOS on-demand and Windows lanes passed on this head

confirmed at c30ff5a6a06cbf107ba13a50eda9bbd0e85c442d: macOS Tests (on demand) shards 1-4 all succeeded (the ci:macos label is on, so the native Darwin run was not skipped). Backend Tests (Windows) 1-8 all succeeded, as did Backend Tests (IPv6, windows-latest), the Windows Fail-Closed Sandbox Contract, Pod Boot Canary (Windows), E2E Gateway Boot (windows-latest) and the kirocrew-gha-windows CodeBuild.
Those are the runs that execute the moved Darwin and Win32 branches natively, and every one of them is green on this exact head.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • PASS punchline: verify the facade_mirror_scan fast path selects exactly the same files as main's patterns

verified by measurement, and the scan file is byte-identical to the previous head's (5cb8dc9d01; this head is a rebase with the same patch-id). A replay ran main's _mentions and this head's over the whole test tree (5,210 files, 449,882 file-by-name pairs): both answered True on the same 5,921 pairs (identical sha256), and the downstream selections match too: 3,068 patching files, 118,647 patch events, 765 syntax-tree reads, the routed patched names of all 50 facades. Zero disagreements.
Only plain dotted identifiers take the fast path; every other spelling still runs main's unchanged per-spelling patterns, and a fuzz pass over generated names and texts shows 0 _mentions disagreements after that gate.
The census guards that consume the scan keep their non-vacuity self-tests (for example test_facade_mirror_guards.py, test_cron_service_bindings.py), which fail when the scan stops finding the patches they know of.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 18, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved on the watch holder's request. Every check on the head passes; the triage cron held it on a size, path, checklist or lane-note rule. Any standing lane note stays on the record.

@bolichen97
bolichen97 merged commit 310ad48 into main Oct 18, 2026
107 checks passed
@bolichen97
bolichen97 deleted the refactor/linecap-s03-platform-compat branch October 18, 2026 22:07
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ci:macos Run the on-demand macOS suite against this PR head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants