Kiro Crew runs on macOS, Linux (x86_64 and ARM), and Windows (native). fcntl,
termios, resource and pty do not exist on Windows, and
os.kill(pid, 0) TERMINATES the target there: it is not a liveness probe.
kiro_crew.platform_compat owns one helper per POSIX call the codebase needs. Reach
for the helper, not the stdlib call, even in code you believe only runs on POSIX — the
import alone is enough to break a Windows install, and the failure lands at import time
in a module a Windows user cannot avoid.
platform_compat is the import and patch surface for every helper below; each of them
is defined in an owner module beside it. Import and patch every one as
platform_compat.<name>, and put new code for a family in the module that owns it.
-
The cross-process file locks (
file_lock,flock_exclusive,acquire_lock/release_lock,try_acquire_lock,open_lock_file,open_create_or_existing,probe_file_persistence) live inplatform_lock_compat, and the owner-only access helpers (current_user_sid,process_owner_sid,local_user_id, the two writability checks,restrict_to_owner/restrict_dir_to_owner,make_owner_only_dir) inplatform_owner_compat. The facade forwards each of their names to that one owner, so a patch there lands on the owner. Those two read the platform flag, the lock modules, the clock,ctypes, the Win32 struct layouts and two shared constants fromplatform_compatwhen they run, so a patch of one of those there reaches them too. -
The rest is carved into
platform_compat_<role>modules, each importing only the ones listed before it:platform_compat_native: the platform flags, the signal and process-creation constants, the Win32 struct layouts and the query-only process handle;platform_compat_proctable: the kernel's process table read directly (macOSlibprocandsysctl, Linux/proc): a pid's parent, state, argv, environment, CPU time and footprint, its children and group members, and who holds a file or itsflock;platform_compat_runtime: the UTF-8 environment and console, the re-exec and exit seams, the process alarm and the boot and awake clocks, the open-file limit,strftime, interpreter discovery and the launcher hops, the desktop bundle's interpreter, the isolated argv a Python child is spawned with, and Windows on Arm;platform_compat_links: links and junctions, the first linked ancestor of a path, the extended-length prefix folded off a path before a containment comparison, the pinned directory that acts on its entries through its descriptor, and the opens that never follow a link at the final name;platform_compat_files: permission changes that never raise, a tree removal that defeats Windows read-only files, the no-replace rename and directory publication, a path's mount identity, the log-tail and lock-sweep opens, owner access restored to every directory of a copied tree, the macOS TCC folders a home-rooted walk prunes, and the remote-volume, executable-file and read-only checks;platform_compat_trust: system binaries resolved only from fixed directories, the environment allowlist, the Windows Known Folders and short names, whether another account can write a path, and launching the file manager or a default app (and whether the host can open one right now: its launcher, and on Linux a desktop session);platform_compat_liveness: whether a pid is alive, a zombie or a thread-group leader, its process group and its thread count, answered without a signal that acts on it;platform_compat_identity: who a process is: its parent, image, command line and argv match, start identity and start time, owning user, Linux namespaces and cgroups, and macOS sandbox;platform_compat_ports: which process is behind a TCP endpoint: the peer of a loopback connection and the listeners on a port;platform_compat_descendants: a process's descendants, walked from one snapshot of the parent map, with the bounds that keep a Windows Toolhelp snapshot finite;platform_compat_winproc: exact Windows process handles, asyncio's handle duplicated for a tree anchor, the handles of a tree's descendants, closing a handle, and the Job object and main-thread resume a suspended child is bounded and started with;platform_compat_wintree: the Windows process trees the gateway owns: the cleanup reservation, the owned spawn and its capture, the pending check, terminating an exact handle and the drains that retire a tree;platform_compat_kill: ending processes: a pid, a group or a tree, the pinned variants, kill-and-reap and terminate-and-reap. It holds every public kill or reap helper and every call toos.killpg,kill_pidorkill_process_tree(pinned or not) in the family, the signal-0 group probepgroup_existsincluded, becausetest/test_kill_chokepoint_ratchet.pyexempts that one file;platform_compat_metrics: resident and peak memory, heap trimming and the malloc arena cap, open descriptors, CPU time, process-subtree samples, and the host's memory, CPU load, memory pressure and power source (power_source).
No carved module imports the facade. The facade installs
kiro_crew._facade_mirror, so a write through it (monkeypatch.setattr,mock.patch) lands on every carved module that binds the same object, as it landed on the one module before the carve. Each of them that logs does so askiro_crew.platform_compat.
The Cross-Platform Portability gate excludes platform_compat.py and the
platform_compat_*.py owners by name: they hold the POSIX primitives this layer exists
to name, so the gate's rules do not apply to them. (Its src/kiro_crew/**/*.py pathspec
also matches no module directly under src/kiro_crew/; see #21019.)
This is the contract. The Windows install and runtime story a user follows is windows-install.md.
Half of these are not "the POSIX call is missing on Windows". They are cases where the
stdlib call exists and answers wrongly: it silently no-ops, it returns a
high-water mark where a live reading was wanted, its unit differs per platform, or it
follows a link planted at the name. A rule of the form "guard it with IS_POSIX"
produces exactly those silent failures, which is why the helper is named per call.
| Need | Use (platform_compat) |
NOT |
|---|---|---|
| Tail a rotating log | open_log_file_for_tail(path) returns a binary read descriptor (caller closes); Windows permits read/write/delete sharing so the writer can rename during a read. Only for log readers, never security pinning. |
plain open held while a Windows writer rolls over |
| File lock | file_lock(fd, exclusive=) / acquire_lock+release_lock / try_acquire_lock, which reads every failure as not taken; try_acquire_lock_or_raise returns False only when another holder has the lock and raises the OSError of a filesystem that cannot lock, so a caller that retries on busy never retries forever. Windows takes a byte-range lock on byte 0 (msvcrt.locking), acquired by spinning on the non-blocking code because msvcrt's own blocking code gives up with EDEADLOCK; the spin is bounded so a stuck holder is reported rather than waited on forever, and both platforms fail CLOSED past the ceiling. That range lock is MANDATORY, unlike POSIX advisory flock: while it is held, byte 0 is unreadable and unwritable through every other descriptor, including another descriptor of the holding process. So a lock descriptor is never written through — not even to place a byte for the range to cover, which a sibling's acquire turns into EACCES on the writer. A byte-range lock covers byte 0 of a ZERO-LENGTH file and still excludes every other descriptor and process, so a lock sidecar stays empty. On the event-loop thread the acquire is a single attempt on both platforms, and flock counts a sibling thread's descriptor as a competing holder, so a caller that must wait runs it through asyncio.to_thread; the refusal names the wait and the limit |
fcntl.flock; writing a byte through a lock descriptor to make its range "lockable" |
| Open a lock file the sweep will lock AND unlink while held | open_lock_file_for_sweep(path): O_RDWR | O_NOFOLLOW on POSIX; on Windows it opens with FILE_SHARE_DELETE, so the held lock's file can still be unlinked |
os.open (the Windows CRT omits FILE_SHARE_DELETE, so unlinking a held lock fails) |
| Create-or-open a lock sidecar race-safely | open_create_or_existing(path, flags, mode, dir_fd=) creates the name EXCLUSIVELY first and, when a sibling already made it, reopens WITHOUT O_CREAT so both hold the sibling's inode; never truncates; returns the raw fd the caller owns. open_lock_file(path) is the context-managed form for a plain lock file; open_lock_file(path, create=False) opens an existing one only and raises FileNotFoundError when it is absent, for a deleter that must not recreate what it locks. A leaf that vanishes between the two opens is a genuine ENOENT left to the caller. Every by-name lock-sidecar open under src/kiro_crew routes through it; the one standalone skill script that cannot import the package (five-whys) spells out the same two opens. test/test_dir_fd_create_race_ratchet.py refuses a new dir_fd= open whose flags carry O_CREAT without O_EXCL, and a by-name os.open of a lock-named path (the path expression or the enclosing function says lock) with the same flags; its LOCK_ALLOWED list carries a reason for each site left as it is |
nonexclusive O_CREAT, which can return ENOENT on Darwin when two callers race to create the same absent name |
| Open a file you write AND lock, never through a link at the name | open_create_no_reparse(path, mode): POSIX is open_create_or_existing with O_RDWR | O_NOFOLLOW and no O_NONBLOCK (a lease break is waited out, as a plain open would); Windows is win_open_no_reparse(path, directory=False, links_only=True), a CreateFileW read/write open-or-create with FILE_FLAG_OPEN_REPARSE_POINT and no FILE_SHARE_DELETE, refusing a link or junction with ELOOP (win_fd_is_link reads the name-surrogate bit of the opened handle's own reparse tag and fails closed), while a regular file carrying a non-link tag such as a cloud-files placeholder opens (the decision-log append shares the open without links_only, refusing every reparse point). open_file_no_reparse(path, links_only=True) is the read-only counterpart. Never truncates; the caller still fstats the descriptor for S_ISREG, since a directory, FIFO or socket at the name can open. To name who holds a lock on that file, pass the descriptor's fstat to flock_owner_pid / pids_holding_file, which accept an os.stat_result |
os.open(path, O_RDWR | O_CREAT) (follows a link at the name, and creates a dangling link's target); an lstat check before the open (a check-to-open window); flock_owner_pid(path) after a no-follow open (re-resolves the name, so it can name the holder of something else) |
| Liveness probe | pid_exists(pid) / pid_liveness(pid) |
os.kill(pid, 0) (kills on Windows!) |
| Process-group liveness | pgroup_exists(pgid); an out-of-native-range positive identity is unknown and therefore conservatively reads as alive, so persisted-state cleanup refuses it without aborting the rest of the sweep |
os.killpg(pgid, 0) directly, or treating an oversized integer as a dead group |
| Kill a process | kill_pid(pid, sig) |
os.kill(pid, sig) |
| Kill a tree | kill_process_tree(pid, sig) |
os.killpg(os.getpgid(pid), sig) |
| Stop a child whose TERM trap must run (an installer that restores what it moved aside) | terminate_and_reap(proc, grace=…, reap_timeout=…) — SIGTERM to the child's own group (read while its leader is alive), pipes drained for up to grace, then SIGKILL to whatever is left and kill_and_reap's bounded reap; shielded against the caller's cancellation. Windows, or a child that does not lead its own group: exactly kill_and_reap. terminate_and_reap_sync(popen, grace=…) is the blocking sibling for a Popen child writing to the caller's terminal (kirocrew update's installer) |
kill_and_reap (SIGKILL first, so the trap never runs) |
| Kill a group the caller CAPTURED | kill_process_group(pgid, sig) — group-addressed; the id must have been read while the group's leader was alive and identity-checked (process_identity.isolated_group_of), the broadcast/self guard refuses with ValueError instead of degrading to a pid, POSIX only |
os.getpgid(pid) at signal time (a recycled pid names a stranger's group) |
Kill a Popen child and its descendants |
kill_popen_tree(proc) — for a child started in its own group (start_new_session / a new Windows process group); signals the group only while proc is unreaped, then proc.kill(), which polls first and so may itself reap a child that already exited; never raises. Collect the status through Popen.wait()/poll(), never a raw waitpid |
proc.kill() alone (a grandchild survives); a group signal after wait() (the pid may name a stranger) |
| Parent PID | get_ppid(pid) (Linux: PPid: through read_proc_status_int), or parent_pid(pid) from read_proc_stat where None must mean unknown |
a text read of /proc/<pid>/status (its Name: line is the raw comm) / libproc |
Fields of /proc/<pid>/stat (parent, group, session, state, start ticks, RSS pages, CPU ticks) and status |
read_proc_stat(pid, proc_root=) -> ProcStat, the reader new code uses: ONE bytes read, comm never decoded (any process may set it to arbitrary bytes through prctl(PR_SET_NAME), and the kernel cuts a multibyte name at 15 bytes mid-character); None when the file is unreadable or the line has no ), otherwise each field is None on its own when its token is missing or not a number, and ProcStat() is the all-unknown reading. cpu_ticks is utime plus stime, so a caller differencing two reads takes the rate and the identity check (start_ticks) from one read. process_age_secs(start_ticks, now=) gives the age on the boottime_now() clock (now for a fixture's own uptime). read_proc_status_int(pid, label) reads one status number (PPid, Threads, VmRSS) from bytes. linux_pgroup_members(pgid) is a group's running members with each one's start ticks from the same read; proc_child_map() the whole host's parent edges. _process_group_supervisor.py runs as python -I -c and must stay stdlib-only, so it carries its own minimal bytes parse. comm is read as bytes and decoded with surrogateescape or replace (linux_process_name, the terminal title), and a status read that needs more than one number decodes with errors="replace". test/test_proc_bytes_reads_gate.py rejects a strict text read of stat, status or comm in src/kiro_crew wherever it can follow the path (a literal, a join, or a name bound in the function, an enclosing one or the module; not a leaf passed in as an argument) |
read_text on the stat or status file (a comm that is not UTF-8 raises UnicodeDecodeError, which an except OSError does not catch and an except ValueError reads as "gone"; a strict ASCII decode fails on any non-ASCII name); splitting before the LAST ); one read per field (a recycled pid can answer the second) |
| Session process identity | get_process_start_id(pid); Windows uses query-only creation FILETIME, Linux start ticks, macOS libproc microseconds with a sysctl KERN_PROC_PID fallback for a zombie (libproc refuses one; the kernel's zombie list still carries the same p_start instant) |
caller-supplied PID or a bare PID without its creation identity |
| Reboot-unique process identity | process_incarnation_id(pid); Linux start ticks plus boot UUID, macOS libproc microseconds, Windows creation FILETIME; None when unavailable. own_process_start_time() caches this for the caller's lifetime. |
bare boot-relative start ticks for a record that survives reboot |
| Listener-owner ancestry | process_descendant_identities(pid, candidate_pids=...) returns each PID, PPID, start token, and its ATOMIC or LSTART source. Rechecks use process_start_id_for_source and never fall across encodings; an unavailable capture source is inconclusive. Before the POSIX fallback filters stable rows, it derives the root subtree from the first ps snapshot and requires every one of those rows to be unchanged in the second; any missing, reparented, or re-identified subtree row returns None, while unrelated rows may churn. The shared tri-state process-start comparator accepts strictly later, excludes strictly earlier, and treats equal coarse or unparseable order as inconclusive. A discovered parent must keep the same identity across its child-list read. Every child named by that read must still have a readable identity and the same parent. A changed parent, vanished child, or reparented child makes the whole walk return None rather than a completed partial result. On Windows each candidate-to-root chain must also keep the same PIDs, creation IDs, and edges across two Toolhelp snapshots, while unrelated siblings may churn. created_after remains a numeric-only Boolean wrapper over that core for its pod and harness callers |
requiring the whole process tree to remain unchanged, accepting a bare descendant PID, filtering unstable root-subtree rows into a completed partial result, comparing an lstart capture with atomic ticks or microtime, treating same-second fallback timestamps or a changed/vanished task as foreign, or maintaining a second comparison implementation |
| macOS zombie state | darwin_pid_is_zombie(pid) (True / False / None unreadable; a pid the kernel does not list reads True); darwin_kinfo_proc(pid) for the record with its start id; darwin_pgroup_members(pgid) lists a process group with each member's zombie flag |
pid_exists as an exit oracle (a zombie is alive to it); pgroup_exists as an empty-group oracle (a retained zombie leader keeps it true); proc_pidinfo on a zombie |
| Zombie state, cross-platform | pid_is_zombie(pid) (True / False / None): Linux reads the state field of /proc/<pid>/stat after the last ) (Z, or X for a process being torn down), macOS defers to darwin_pid_is_zombie, Windows and an unreadable pid answer None — the "is it still RUNNING" question a survivor check asks beside pid_exists (a signalled child sits in the zombie state until it is collected); never signals |
pid_exists alone as a running-vs-exited oracle; reading the state before the first ) (a comm may contain spaces and parentheses); treating None as "not a zombie" |
| Linux execution-boundary equality | process_namespaces_match(pid, reference_pid); compares user and mount namespace inodes with incarnation checks; None on unreadable or unsupported platforms |
absent current ancestry as proof that a process is unconfined |
| macOS inherited sandbox state | process_is_sandboxed(pid); read-only Seatbelt query with an incarnation check; None on errors or other platforms |
treating an unavailable query as unsandboxed |
| macOS sandbox file-read permission | process_can_read_under_sandbox(pid, trusted_absolute_path); queries Seatbelt without opening the file, checks incarnation before and after, and returns None on unknown |
treating all sandboxed processes as either private or Global; a query error as a grant |
| Loopback TCP caller PID | get_tcp_peer_pid(sockname[:2], peername[:2]); unique ESTABLISHED reverse IPv4/IPv6 tuple, failure is unknown. Linux maps the kernel socket inode to process FDs; macOS uses trusted system lsof; Windows uses the owner-PID table. Offload this probe; prefer Unix peer credentials where available. |
HTTP headers, a listener's PID, or matching only a port |
| Match process cmdline | process_matches(pid, needles) |
/proc/<pid>/cmdline / ps |
| Read Linux process name | linux_process_name(pid); exact kernel comm, None off Linux or on an unreadable/empty value. Fixture tests may pass proc_root=. |
reading /proc/<pid>/comm outside the compatibility layer |
| Compare process cgroups | process_cgroups_match(pid, reference_pid); compares stable unified cgroup v2 membership and returns None off Linux, on cgroup v1, on unreadable/changing membership, or when identity is otherwise inconclusive. Fixture tests may pass proc_root=. |
comparing one /proc/<pid>/cgroup read without stability rechecks |
| Process start time (PID-reuse guard) | process_start_time(pid) |
/proc/<pid>/stat / ps -o lstart= (both answer None on Windows, so the guard silently never confirms) |
This process's effective uid, to derive a per-user path from (/run/user/<uid>/bus) |
effective_uid(): os.geteuid() on POSIX, None on Windows, which has no uid; a caller reads None as "no such path on this platform" (github_runner._user_bus_socket_candidates then offers no uid-derived candidate and the provider CLI child gets no DBUS_SESSION_BUS_ADDRESS at all) |
os.geteuid() / os.getuid() reached directly (neither exists on Windows, so the import-time or call-time AttributeError takes the whole builder down); formatting a guessed uid into the path |
| Is this pid a PROCESS rather than a thread | is_thread_group_leader(pid) for one pid; live_thread_group_leaders() once for a whole sweep |
pid_exists(pid) alone (Linux numbers threads from the pid space and POSIX permits signalling a tid, so a pid recycled as a THREAD of an unrelated process reads as alive forever). Both answer None, never False, when unknowable — treat None as "retain", never as licence to act |
| Signals | platform_compat.SIGKILL / SIGTERM |
signal.SIGKILL (undefined on Windows) |
| Spawn isolation | start_new_session=IS_POSIX + creationflags=CREATE_NEW_PROCESS_GROUP |
bare start_new_session=True |
| Spawn a console helper from the windowless gateway | creationflags=_SUBPROCESS_NO_WINDOW (CREATE_NO_WINDOW on Windows, 0 on POSIX) |
no flag (each helper flashes a console window) |
| Walk a tree without leaving it | skip entries where lstat_is_name_surrogate(info) is true (Windows junctions and other name-surrogate reparse points); remove a tree in a sweep with rmtree_force(path) |
S_ISDIR alone on an lstat result (it reports a junction as a plain directory and walks into the target) |
| Tell two mounts of one directory apart (a bind mount shares its source's device and inode) | mount_identity(path, dir_fd=) -> (mount id, device major, device minor, inode) through statx(STATX_MNT_ID), following symlinks and /proc magic links; with dir_fd and an empty path it names the descriptor. None off Linux, before Linux 5.8, or on any failure. Reached through syscall() where glibc has no statx wrapper, as rename_noreplace is |
os.stat alone, which reports a bind and its source as one directory |
Remove a tree git produced (a clone, a --local clone, a directory with a .git) |
rmtree_force(path) from a thread, or _rmtree_force_settled(path) where a cancelled caller must not leave the delete running (registry_pipeline). It clears the read-only bit on a file Windows refuses to unlink and retries once, never raises, and returns whether the path is gone, so a caller that restores something into the same path checks the answer. A tree that survives (a file another process holds open) is set aside, not collided with: _restore_moved_aside renames it to a .partial-* sibling before the restore |
shutil.rmtree(path, ignore_errors=True) (git writes .git/objects/pack/* read-only; Windows refuses the unlink, ignore_errors swallows it, and the tree stays on disk while the caller reports success). Keep ignore_errors=True only where the tree holds nothing git wrote: a copy that drops .git (manager._COPY_IGNORE), a scratch or staging directory, or a linked worktree whose .git is a file. test/test_git_tree_removal_windows.py pins every site that removes a git tree |
| Resolve a path for a containment check | resolve(strict=True), handling FileNotFoundError on its own and failing closed on any other error |
non-strict Path.resolve() (on Windows it collapses a self-pointing reparse point lexically without raising, so the loop passes as contained) |
| Wait on a subprocess PIPE with a deadline | a daemon reader thread feeding a queue.Queue, consumed with a bounded get (testing/harness.py's _StdoutPump) |
selectors.DefaultSelector() on the pipe (select()-based on Windows, which accepts SOCKETS only, so registering a pipe RAISES there) |
| Re-enter an edition's stable gateway launcher | reexec_launcher(launcher, args) after gateway_restart.resolve_restart_launcher() validates it; keeps the dispatch pathname, original arguments and UTF-8 environment, cancels a managed-venv apply in flight (cancel_wheel_applies_in_flight), and puts every variable registered with keep_for_reexec back into os.environ right before os.execv |
resolving the symlink basename away, passing Python -m flags to a launcher, or evaluating a shell command |
| Re-exec the current Python module | reexec_python_module(module, args); like reexec_launcher, it cancels a managed-venv apply in flight, then restores the UTF-8 environment and the keep_for_reexec variables right before os.execv |
os.execv(sys.executable, [sys.executable, ...]) (breaks when the Windows interpreter path contains spaces) |
| Take a variable out of the environment for descendants while this process's own exec successor still gets it (the managed-service launch marker) | keep_for_reexec(name, value) after popping it; kept_for_reexec() reads what is held. Only the two reexec seams restore it, so a child spawned meanwhile does not inherit it, and if execv raises, os.environ keeps it until the process exits |
re-setting it in os.environ by hand before an exec (every child spawned in between inherits it); an exec outside the two reexec seams (the successor loses it) |
| End the process at once, other than the gateway's own final exit | hard_exit(code): cancels a managed-venv apply in flight, then os._exit (the second-signal force exit, the owner's /kirocrew restart) |
a bare os._exit (a managed-venv apply in flight keeps writing its tree after the process that supervised it is gone) |
| Stop a managed-venv apply at every exec, hard exit or shutdown | cancel_wheel_applies_in_flight(reason): looks kiro_crew.platform.wheel_apply up in sys.modules (never imports it) and calls its cancel_wheel_applies(reason) when loaded; both exec seams and hard_exit call it, and a shutdown that wants the apply stopped before its own teardown calls it itself. Synchronous, quick, safe to call twice; a cancel that raises never stops the exit |
an atexit handler (an exec and os._exit both skip it); a general exit-hook registry (it had one registrant, so it abstracted over nothing) |
| Launch a Kiro Crew-owned Python child | isolated_python_argv(*args, executable=...); it adds -s for the bundle and parents whose user site is already unavailable, unless the option prefix carries -s or stronger -I. A self-launch through -m kiro_crew... also passes -P (safe path: the cwd is not on sys.path), pinned by test/test_stdlib_shadow.py |
a raw [sys.executable, ...], or an ad hoc PYTHONNOUSERSITE env that another spawn path can omit |
| Replace the current process with another program (a supervised service body) | spawn a child, record its pid + process_start_time, and wait() on it under IS_WINDOWS (see pod.windows.supervise_gateway) |
os.execve (on Windows this SPAWNS and terminates the caller, so the pid changes and the service manager sees the unit exit while the real program keeps running orphaned) |
Hand a one-shot command to another program and pass its exit code back (kirocrew pod exec) |
os.execve on POSIX; under IS_WINDOWS a subprocess.Popen child with inherited stdio and cwd, wait()ed through any KeyboardInterrupt (Ctrl+C reaches the child too), whose return code the caller returns (see pod.runtime_boot.exec_in_pod) |
os.execve on Windows (the caller exits 0 or crashes with 0xC0000005 instead of returning the command's code); subprocess.run (it kills the child on Ctrl+C, which ends a running chat) |
Make print() reach a non-terminal stdout as it is printed (the gateway's status lines under a service manager) |
ensure_line_buffered_stdout() once at gateway start, before the first status print: a stdout that is not a tty is reconfigured to line_buffering=True; a tty is left untouched (already line-buffered), and a stream with no reconfigure (absent, closed, a StringIO, a plain object a launcher left behind) is left as it is. sys.stderr needs nothing: CPython line-buffers it on every attachment. Independent of ensure_utf8_console(), which keeps the encoding job and runs first. Contract: cli |
flush=True on each print() (every new print has to remember it); PYTHONUNBUFFERED=1 in a generated unit (reaches that one launcher and no installed unit, launchd agent, Desktop supervisor or detached gateway); turning the prints into logging records (changes what the log carries) |
| Open an exact Windows process object for later tree discovery/termination | open_process_termination_handle(pid, expected_token) validates the opened handle's creation identity before returning it (caller closes with close_process_handle); combine with descendant_termination_handles so the anchored root and each retained child receive a final post-exit snapshot |
opening by PID and checking the token beforehand (PID reuse can occur between those operations) |
| Race-free Job object assignment | creationflags |= CREATE_SUSPENDED, then apply_job_limits, then resume_process_main_thread |
assigning a job to an already-running child (descendants it already spawned escape) |
| Fork-bomb / memory ceiling on a spawned tree | sandbox.apply_windows_resource_ceiling(pid) after the spawn, alongside cgroup_scope_argv |
cgroup_scope_argv alone (a no-op on Windows, so no ceiling at all) |
Size an ActiveProcessLimit as "this Python child and nothing else" |
1 + python_launcher_hops() (1 when sys.executable is a venv's Scripts\python.exe, the redirector that CreateProcess-es the base interpreter as its own child and stays alive as its parent; 0 for an interpreter and on POSIX); kill a timed-out child as a TREE (kill_process_tree) so the interpreter goes with its redirector |
a literal max_procs=1 (refuses the redirector's spawn: Unable to create process using ..., exit 101, so the child never runs from a venv); proc.kill() on the redirector alone |
| File mode | chmod_safe(path, mode) / fchmod_safe(fd, mode) |
os.chmod / os.fchmod (no os.fchmod on Windows) |
| Owner-only secret (fail-loud) | restrict_to_owner(path) |
os.chmod(path, 0o600) under if IS_POSIX (silent no-op leaves secrets world-readable) |
| Owner-only secret directory (fail-loud, inheritable) | restrict_dir_to_owner(path); make_owner_only_dir(path) to also create it (its tighten step is best-effort) |
restrict_to_owner(path) on a directory (its Windows grants carry no (OI)(CI), so files created inside land on the default DACL, not owner-only; its 0o600 also drops the execute bit a directory needs) |
| Create a file or directory in the data home | kiro_crew.owner_only_files: open(path, mode, opener=owner_only_opener) or write_text_owner_only for a file, prepare_owner_only_sqlite(db) immediately before a write-capable SQLite connect (SQLite gives -wal/-shm/-journal the database file's own mode), mkdirs_owner_only(path) for a directory chain, ensure_directory(path) / owner_only_opener_for(path) / write_text_owner_only_in_home(path, text) where the target is usually in the data home but may be configured elsewhere (outside the home each behaves exactly like the plain call); atomic_write already defaults to 0o600 (and 0o700 for directories it creates) for a target inside the data home. The policy -- every file there 0600, every directory 0700, set at creation -- and the once-per-start sweep that repairs older trees (tighten_data_home, run on a worker thread once the dashboard listener serves, touching only the fixed store list STARTUP_SWEEP_STORES, never following links and skipping hard-linked files) are stated in that module's docstring. POSIX only; on Windows each helper keeps the previous behaviour and the data home's inheritable DACL applies |
open(path, "w"), Path.write_text, Path.mkdir(parents=True) or os.open(..., 0o644) for a data-home path (the umask default, 0644/0755, is readable by other local accounts); chmod after the write (a window in which the file is readable); open + fchmod + close to tighten an existing store file (closing any descriptor releases this process's POSIX record locks on it, which SQLite relies on; prepare_owner_only_sqlite and the sweep change the mode without opening the file); os.umask(0o077) (inherited by every child, so files agents write into the user's own repositories would come out 0600) |
| Read a state file that a writer replaces atomically (a store's JSON; a record a request, a gate or an install depends on) | kiro_crew.atomic_write.read_bytes_with_retry(path), then decode and parse. A Windows sharing violation (PermissionError, WinError 32, while the writer's replace is in flight) is retried inside a bounded budget. An absent file and a damaged one are not retried and reach the reader's own handling, and a hold that outlasts the budget raises as before, so a gate or refusal that fails closed stays closed. The retry runs only off the event loop: a reader reached from a coroutine is offloaded with asyncio.to_thread |
path.read_text() / path.read_bytes() (POSIX permits the overlapping read, so only the Windows matrix and Windows hosts ever fail) |
| Is a path on a NETWORK volume | path_volume_is_remote(path) (Windows: the volume ROOT's drive type through windows_acl.volume_is_remote, so a UNC path and a mapped drive both read remote, at no SMB round trip; None off Windows, where the caller has a mount table — taskq.store.detect_network_filesystem is the caller) |
reading a failed query, DRIVE_UNKNOWN or a non-Windows host as "local" (windows_acl.volume_is_local collapses unknown onto False on purpose; that is the trust answer, not this one) |
| Confirm a Linux readonly filesystem | is_readonly_filesystem(path); false for other platforms or probe failure. Used to reject a private-runtime diagnostic marker planted in the writable host home, and to send a memory store reader on a confirmed read-only mount straight to its read-only lock open (elsewhere the reader falls back on the refused write itself). |
os.statvfs in a cross-platform consumer, or readonly file mode alone |
| Is this host on mains or battery | power_source() → POWER_AC / POWER_BATTERY / POWER_UNKNOWN. Linux reads /sys/class/power_supply: external power is any type == "Mains" supply or any type == "USB" supply whose scope is not Device (the USB-C port supplies, ucsi-source-psy-*), and ANY online one means mains, so a USB-C PD charger counts even when only its port reports it; a tree with no external supply is UNKNOWN, not battery, so a desktop with a peripheral's battery never reads as a laptop. Battery needs every external supply read offline: an unreadable one may be the charger, so with none online the answer is UNKNOWN. Battery also needs a system battery (type == "Battery", scope not Device), so a desktop whose only external supply is an idle USB-C port reads UNKNOWN. Windows reads GetSystemPowerStatus, whose ACLineStatus 255 stays UNKNOWN. macOS has no reader yet and answers UNKNOWN, so it never throttles. Never raises, never cached: callers read it once per unit of work. Fixture tests pass sysfs_root= to _linux_power_source and patch _windows_ac_line_status |
treating POWER_UNKNOWN as battery (every consumer MUST read it as mains: deferring optional work on an unreadable probe is a silent, permanent stoppage), reading /sys/class/power_supply outside this layer, requiring a supply name like AC0, or caching the answer across units of work |
| Directory link | symlink_or_junction(target, link) |
os.symlink (WinError 1314 without elevation) |
| Detect/remove a dir link | is_link_or_junction(path) / unlink_link_or_junction(path) |
path.is_symlink() (misses a Windows junction) |
| Compare a resolved path against an unresolved one | strip_extended_length_prefix(path) on BOTH sides before comparing |
comparing the two spellings as Path.resolve returns them (on Windows ntpath.realpath keeps the extended-length prefix when its prefix-strip re-check races a concurrent swap of the same file, so a prefixed child against an unprefixed parent reads as a path escape; the fold is LEXICAL and must not re-resolve, which would bless the redirect the caller is testing for) |
| Read, write or store a path after folding its extended-length prefix | refuse it first when names_a_verbatim_only_file(path) is True |
using the folded path as-is (a component ending in a dot or a space, or a DOS device stem such as CON, is reachable only through the \\?\ spelling; ordinary Win32 lookup trims or remaps it, so the folded path names a sibling or a device instead of the file that passed the checks) |
| Hold a directory in place while a child writes into it by path | pin_directory(path) (then os.close) |
os.open(dir, O_RDONLY) (EACCES on Windows, and even where it opens it follows a link planted at the name) |
| Act on the ENTRIES of a directory you inspected (screen-then-remove, screen-then-descend) | pinned_directory(path) yielding PinnedDirectory (names / is_link / is_dir / unlink / rmdir / child / child_if_real_dir / read_text); a parent stays pinned while its child is in use, so a chain of them pins the whole path, and child refuses past PINNED_TREE_MAX_DEPTH (64) levels with ENAMETOOLONG so a planted chain cannot spend another frame or descriptor. Descend with child_if_real_dir, which answers None when what is at the name is no longer a real directory and RE-RAISES for one that is: it holds the errno-agnostic dispatch (a refused O_DIRECTORY | O_NOFOLLOW open is ENOTDIR on some kernels, ELOOP on others, NotADirectoryError on Windows) in one place, and its callers supply the differing action — two remove the entry, one deliberately leaves it. Its re-raise is also how the depth refusal reaches a caller, so an over-deep tree fails the operation instead of being unlinked as though it were a link |
screening a NAME and then operating on that name -- every stdlib walker re-resolves it in between, and os.walk's own descent re-check is os.path.islink, which is False for a junction, while rglob descends one unconditionally. The two platforms need OPPOSITE routes, which is why this is a helper rather than an IS_POSIX branch per call site: dir_fd-relative calls on POSIX, where the pin does NOT block a rename, and by-path calls on Windows, where there are no dir_fd operations at all and the pin is what holds the path still. Also: hand-spelling the refused-open fallback at a call site, where a fourth copy gets the errno dispatch subtly wrong |
| READ a file you judged in the same traversal (screen-then-read) | PinnedDirectory.read_text(name, max_bytes=…) -- the open itself refuses a link at the name, the descriptor's own fstat rejects a non-regular entry, a hardlink and anything over max_bytes, and the open is non-blocking so a FIFO cannot stall the read. The size is asked of the OPEN DESCRIPTOR, not of a stat taken before it, and the read itself is bounded too, so a file that grows between the two stops at the cap. The layers under it are private on purpose: reaching for a raw descriptor would be operating outside the pin |
screening a name and then reading that name -- the entry is re-resolved in between, and the screen only refuses a link that was PRESENT at check time, so a flip-flop serves a file of the adversary's choosing. Also: a pre-open stat for the size, which measures a different file than the one the read then opens |
| ENUMERATE a directory whose contents an agent writes | PinnedDirectory.names_bounded(limit), which answers None when the directory holds more than limit entries |
names() (or sorted(os.listdir(...))) on such a tree: the eager list IS the exhaustion, allocated in full before any budget the caller applies afterwards could refuse it. Returning the first limit names instead of None would be worse than either -- the caller acts on a partial directory while believing it saw all of it |
| Process RSS (live) / peak RSS / CPU | proc_rss_bytes() / proc_peak_rss_bytes() / proc_cpu_seconds() |
resource.getrusage (ru_maxrss is a high-water mark, never a live reading, and its unit is KiB on Linux but bytes on macOS). The peak on Linux is NOT ru_maxrss: execve seeds it with the pre-exec image's peak, so a gateway started from a large parent would report that parent's number for life; Linux reads its own /proc/self/status VmHWM instead, monotonic across reads (the kernel folds live RSS into hiwater_rss lazily, so raw consecutive readings can dip a few hundred KiB), and an unreadable /proc is the documented 0, never the inherited figure. pdf_extract_child carries the same VmHWM parser rather than importing this module (its imports stay minimal under a capped address space) |
| Another process's macOS memory footprint | proc_phys_footprint_bytes_for_pid(pid) |
proc_pid_rusage(pid, RUSAGE_INFO_V2) -> ri_phys_footprint through libproc (no subprocess, no entitlement for a same-uid pid); None off macOS or when unreadable. This is the figure jetsam acts on and Activity Monitor's "Memory" column shows: it counts compressed and swapped pages, which ps RSS omits, so an idle process that has grown can read a small fraction of its real cost through ps (16x measured). acp/runtime_process_tree measures each pid of a macOS tree by it, with ps RSS as the per-pid fallback, so the runtime ceilings and the Sessions panel read it there. diag/procs (debug_processes) fills each macOS node's rss_kb from it, floored to KiB, with no ps fallback: an unreadable pid leaves that node's rss_kb null and is counted in degraded, and the rest of the roster is unaffected |
| A deadline that survives a host suspend and needs no thread or GIL | arm_process_alarm(seconds) (0 cancels), guarded by process_alarm_available(): the kernel's setitimer(ITIMER_REAL), which Linux runs on CLOCK_MONOTONIC and macOS on the absolute mach timebase, so a pending deadline keeps its remaining time across a sleep instead of firing on resume; pair it with faulthandler.register(SIGALRM, ...) for a GIL-free stack dump, released with faulthandler.unregister and registered afresh on every arm (a repeat register reinstalls nothing while faulthandler believes it still holds the signal, so a temporary owner that handed SIGALRM back with SIG_DFL would otherwise leave the next alarm to end the process without a dump). False on Windows, which has no such timer — the caller falls back to a mechanism it names for that platform (the loop watchdog uses faulthandler's timer thread there). The timer belongs to the process image that armed it and to no successor: execve preserves ITIMER_REAL while it resets a caught SIGALRM to its default disposition, so reexec_launcher / reexec_python_module cancel it immediately before os.execv, and the gateway entrypoint clears any deadline that still arrived (loop_watchdog.disarm_inherited_alarm, only while SIGALRM is at its default disposition) |
faulthandler.dump_traceback_later as a standing deadline (its wait is CLOCK_REALTIME-based on every macOS build and on any Linux build without sem_clockwait, so a suspend longer than the budget fires it on resume); signal.setitimer / signal.SIGALRM reached directly (neither exists on Windows); a bare repeat faulthandler.register as a way to re-install the handler; an os.execv outside the two reexec seams while a deadline is pending (the successor is ended by a signal it never armed) |
| Now on the suspend-inclusive clock (dating a process start, or measuring a sleep) | boottime_now(): CLOCK_BOOTTIME on Linux (it counts time the host spent suspended, as /proc/uptime and the starttime field of /proc/<pid>/stat do), time.time() on macOS (the clock libproc dates process starts on; it can step, so the liveness oracle pairs it with acp/liveness_proc.steady_now), None where neither exists — a caller reads None as "cannot say", never as a time. The liveness oracle stamps a tool dispatch on it, and the loop watchdog compares its advance against time.monotonic() across one poll to name a resume |
time.monotonic() against a /proc process age (CLOCK_MONOTONIC stands still through a suspend, so a boot-clock age minus a monotonic stamp places a live child before its own dispatch); time.clock_gettime(time.CLOCK_BOOTTIME) outside the compatibility layer (absent on macOS and Windows); importing the reader from kiro_crew.acp in application code (the agent-SDK boundary gate refuses the edge) |
| Now on a clock a host suspend does not advance (how long a loop has been silent) | awake_now(): time.monotonic() on Linux (CLOCK_MONOTONIC) and macOS (the mach timebase); on Windows, whose time.monotonic() counts a sleep, the unbiased interrupt time (QueryUnbiasedInterruptTime), falling back to time.monotonic() only if that call fails. The loop watchdog's silence and the gateway heartbeat's lag read it, so a resume does not read as a stall |
time.monotonic() for a silence that must not count a Windows sleep (it counts one there, so a resume reads as the whole sleep without a beat) |
| Available host memory | host_available_mib() (0 = unknown, never 0 = no memory) |
/proc/meminfo directly (Linux-only, so the bound built on it silently vanishes on macOS and Windows) |
| macOS kernel memory pressure | memory_pressure_level(): kern.memorystatus_vm_pressure_level through sysctlbyname on the cached _darwin_sysctl_handle(), in-process (built once under a lock, both prototypes declared before the handle is published, so a concurrent first call never reads None). It answers MEMORY_PRESSURE_NORMAL (1), MEMORY_PRESSURE_WARN (2) or MEMORY_PRESSURE_CRITICAL (4): XNU's NOTE_MEMORYSTATUS_PRESSURE_*, the same values as libdispatch's DISPATCH_MEMORYPRESSURE_*, with the kernel's internal "urgent" level reported as WARN. memory_pressure_name(level) renders it. None off macOS and on any failure (no libc, a failed call, a wrong-size answer, an unknown value), and a caller fails open on None. The level is the kernel's lagging verdict (subagent.md, macOS: the kernel memory-pressure hold): use it as a backstop beside a figure, never as one |
a sysctl subprocess (the app sandbox can deny the spawn, and callers run on the event loop); a fresh CDLL per read; treating the level as a measure of free memory, or a NORMAL reading as proof the host has room |
| FD soft limit | raise_nofile_soft_limit(n) |
resource.setrlimit |
| Port to PID | find_listening_pids(port) / listening_pid_tool_available(); find_port_listeners(port) when ownership must be scoped to the local address actually probed; probe_port_listeners(port) when completed-empty must be distinguished from timeout or execution failure; process_owns_loopback_listener(pid, port) for per-process ownership through Linux procfs, PID-scoped lsof, or Windows GetExtendedTcpTable owner-PID tables |
lsof or netstat directly |
Spawn a system tool (ps, lsof, netstat, taskkill) |
trusted_system_bin(name), treating None as "unavailable" |
a bare argv name (resolved through a PATH that can lead with same-uid-writable dirs) |
| Resolve a system tool on the event loop (a periodically refreshed capability probe) | trusted_system_bin_quiet(name): the same fixed-directory lookup with no miss diagnostic, reporting a miss in the caller's own words |
trusted_system_bin, whose miss diagnostic walks PATH with shutil.which and can hang on an entry on a stalled mount |
| Decide whether an executable's PATH can be trusted (ownership, mode bits, writability by some account) | traversed_components(path) for the ENUMERATION, then the site's own predicate over every entry. It resolves the path COMPONENT BY COMPONENT, expanding each symlink it meets, and returns every directory the walk actually reads — the original spelling's side, each hop's side and the target's side — plus the final target, root-first, each once; None on OSError or past _MAX_SYMLINK_HOPS, which every caller treats as a refusal. traversed_components_and_links(path) is the same walk returning (components, links), where links names each symlink it expanded, spelled under a directory components names: a question that admits a sticky directory needs their owners too, because an account that may write a sticky directory replaces only its own entries there. The trust QUESTION stays with the caller, because the sites ask different ones and must keep asking them: _is_root_owned_path (trusted_aws_bin: root's alone to change), github_runner.validate_provider_executable POSIX branch (not another uid's, not world-writable unless sticky; strict mode root-owned and unwritable; its multicall-link rule, Linux-only because elsewhere an ACL can grant write the mode bits do not show, reads traversed_components_and_links, since it admits sticky directories), browser_cli.install._gateway_writable_component POSIX branch (not writable by this gateway process), service.apparmor._substitutable_by_others (no 0o022 bit, no third-account owner). Windows branches keep their ACL-driven lexical chains; the walker is os.sep-rooted and does not model drive anchors or junctions |
realpath and then .parents / os.path.dirname (collapses the chain, so a hop through writable space — gh -> /tmp/link -> /usr/bin/gh — is never stat'd); a lexical .parents walk over the spelling as given (os.stat follows symlinks and dirname does not, so for /usr/local/bin -> /opt/x/bin the target's parent /opt/x is never visited); or walking BOTH endpoints' lexical chains (still names no hop in the middle). Adding a fourth spelling of the walk for a new site |
| Decide whether a group write bit admits an account other than this one | group_write_admits_another_account(path, gid) with the path's st_gid: the one question every check crediting a group write bit to its owner asks, so one directory gets one answer (cloud.source._first_replaceable for the chain holding a staged source tarball, github_runner._who_can_change for what a provider CLI link's path reads). None means the bit admits this account alone. It reads the POSIX access ACL first (_acl_admits_another_account): with an extended ACL the group bits are its MASK, so a named entry can write behind a bit that looks private; only an EFFECTIVE write counts (entry AND mask), a named user that is this account or root is trusted, and a named group gets the membership question. No ACL API (macOS, BSD) or no ACL leaves the mode bits as the test; any other read failure or an unrecognised value fails closed. Then the membership (_group_shared_with_another_account): gr_mem of every group entry carrying the gid (getgrgid returns one, and a second entry from groupadd -o grants the gid to its own members), plus a passwd enumeration that must contain this account. Any other answer is a noun phrase naming whom the bit may admit, for an operator-facing message; anything unreadable is such an answer, never None. POSIX only: on Windows the staging walk reads the ACL instead, and the link rule runs only on Linux |
counting every group write bit as a foreign writer (a user-private group's bit is the owner's own); reading the bit as the owning group's permission without reading the ACL; refusing every ACL (a read-only entry or a default-only ACL lets no one else write); trusting gr_mem alone (an account whose primary group it is never appears there), getgrgid's one entry, or a passwd enumeration that does not contain this account; a check asking one half, or its own copy of the question |
Spawn the AWS CLI (aws) |
trusted_aws_bin() — trusted_system_bin plus a /usr/local/bin fallback (the installers' default --bin-dir), accepted only when _is_root_owned_path finds every entry of traversed_components (see the row above: every directory the walk reads, including the directories on a symlinked component's target side, plus the final target) root-owned, not group/world-writable, and (via os.access(..., effective_ids=True), the only form that reads a POSIX ACL) not writable by the non-root account through an ACL entry st_mode cannot express. Running AS root DECLINES: there os.access answers True for everything, so the ACL arm has no signal, and the entry it would catch grants a NON-root user write — the one case root must not execute. Only the /usr/local/bin fallback is lost under root; trusted_system_bin does not route through this. The fallback also refuses a #! SCRIPT (_is_native_program): a shebang names its interpreter in the file's CONTENT, which the path walk never validated, and sudo pip install awscli against a pyenv Python produces exactly that — AWS CLI v2 ships a native executable, so the case this exists for is unaffected. Both conditions live in ONE predicate, _local_aws_bin_is_trusted, because the resolver and aws_bin_declined_on_ownership both ask and must never contradict each other about one file. Debian policy has /usr/local subdirectories root:staff mode 2775, so the fallback DECLINES by default on stock Debian/Ubuntu: intended, because a staff member can replace the binary. A diagnostic must then report the decline with aws_bin_declined_on_ownership() rather than as absence |
adding /usr/local/bin to _TRUSTED_SYSTEM_BIN_DIRS (Intel macOS Homebrew owns that directory as the console user, so membership alone would let a same-uid process supply ps, lsof and every other pinned tool); or validating the path with realpath (collapses a chain, so a hop through writable space vanishes) or a lexical dirname walk (os.stat follows symlinks and dirname does not, so a symlinked component's target ancestors are never seen) |
Read a Windows system tool's ANSWER (schtasks /Query, tasklist, sc query) |
the tool's exit code, or a fact the program under test recorded itself | parsing its stdout (column headers AND status words are translated by the UI language, so a match on "Running" reports every instance down on a non-English host — the fail-OPEN direction) |
| strftime no-pad | strftime(dt, "%-I") |
bare dt.strftime("%-I") (ValueError on Windows) |
The shared POSIX process snapshot requests each column separately:
ps -A -o pid= -o ppid= -o lstart=. Some ps implementations parse the commas
after an empty header as part of that header, returning only PIDs. Separate
output options preserve the parent and start-time fields that descendant
discovery and PID-reuse checks need, even when the combined form exits successfully.
Its relationship to pinned_fs. That module owns this discipline and says so —
mechanism in one place, callers as thin consumers — and PinnedDirectory is the
cross-platform arm of it, not a second opinion. What decides the split is the import
direction: pinned_fs imports THIS module for its Windows no-reparse open, so nothing
here can import it back. The Windows arm has to live at this layer anyway, because it IS
platform mechanism (CreateFileW, a share mode omitting FILE_SHARE_DELETE,
st_file_attributes) rather than the dir_fd discipline pinned_fs is built from —
and supports_pinned_walk() means "dir_fd opens are available" to every one of its
existing consumers, which read it to DEGRADE on Windows, so a Windows-capable pin cannot
hide behind that boolean without changing what it promises them. The one thing genuinely
spelled twice is the POSIX open-flag triple (pinned_dir_flags() here,
dir_flags() there); test_pinned_directory.py::TestItDoesNotDivergeFromPinnedFs
asserts the two are equal and records the one place the modules deliberately differ (a
hardlinked file is refused on this read, where pinned_fs.read_file_pinned allows it),
so neither can drift without a red test.
Every Kiro Crew-owned Python service, helper, and runtime dependency installer that
can run under the bundled interpreter routes argv through isolated_python_argv.
The helper adds -s for the bundle and for parents whose user site is already
unavailable, removing the interpreter's user-site directory without dropping
PYTHONPATH or other required environment settings. A -m kiro_crew...
self-launch additionally passes -P, so the cwd is not imported from. A caller
that already carries -I stays unchanged; -I is stronger because it also ignores
Python environment variables and the cwd. A non-bundled parent that currently allows
the user site preserves that policy because Kiro Crew itself may be installed there.
A module-style child that imports kiro_crew from the parent's own user site
keeps the parent's user-site policy. Isolation is forced only when the parent's
own launch rewrite injects the child's import path, never because the child
inherited PYTHONPATH. A caller MUST therefore pass force_isolation=True
only for that launcher-injected path, such as the path-based dependency shim,
or for a script or entry path that does not import kiro_crew from the user
site. The explicit override keeps -s on non-bundled, user-site-enabled
interpreters only where removing the user site cannot remove the child target.
This contract does not apply to user-authored cron scripts, project test commands, or
other workloads whose documented environment may include --user packages. The
explicit inventory in test/test_internal_python_isolation.py names the internal
boundaries; any resident runtime worker's module launch follows the same unforced
parent-policy decision. Adding one requires routing it through the helper and adding it
to that inventory, so a later spawn cannot silently return to the user-site-dependent
behavior.
kiro_crew._ssl_compat._ensure_ssl_certs runs in the startup prelude of every entry
point (__main__, cli, mcp_gateway.gatewayd) before any HTTPS client caches an
SSL context. Its order is the clean-start order: an operator's SSL_CERT_FILE wins
outright (one warning when the file it names cannot be found, nothing else touched);
Windows exports nothing (rustls-native-certs in the kiro-cli child treats
SSL_CERT_FILE as a replacement for the platform store, so a public-roots bundle
would subtract every private CA); macOS injects Security.framework evaluation for
this process; then the interpreter's own default cafile (nothing to export), then the
Linux distribution bundles in _CA_CANDIDATES, then certifi's bundle. The found
bundle is exported as SSL_CERT_FILE / REQUESTS_CA_BUNDLE for the children that
cannot inherit a process-local injection (kiro-cli, Node MCP servers).
The certifi export is install-pinned: certifi.where() is
<prefix>/lib/pythonX.Y/site-packages/certifi/cacert.pem inside the running install.
The in-app restart seams hand the successor this process's environment
(platform_compat.reexec_launcher / reexec_python_module behind the dashboard's
update and restart actions, service.live_target.maybe_reexec for a live-target
cutover), so a successor re-enters the prelude holding its predecessor's value.
Honoured as an operator override, that value keeps the successor pointing at the
previous install's bundle; once an upgrade or an installer re-run deletes that tree
every TLS handshake fails until a restart from a clean environment.
The rule is shared with the other install-pinned runtime export,
LLAMA_CPP_LIB_PATH: a value the runtime exported is its own transitional value, not an
operator's, however it is inherited. That variable reaches the rule by the opposite
route, because no child needs it: each entry prelude calls drop_inherited_lib_path to
REMOVE an inherited bundled-shaped or empty value outright (keeping it in
dropped_inherited_lib_path for kirocrew doctor), operator_lib_path_override is the
one classifier for what counts as an operator's value, and the loader hands this install's
directory to the vendored runtime through the process-local sys.modules seam
_LIB_PATH_SEAM rather than the environment — so nothing is left in the environment for a
marker to vouch for. Here the export must stay in the environment — the children need it — so the
runtime publishes its provenance beside it, one marker per variable it assigns:
KIROCREW_EXPORTED_SSL_CERT_FILE and KIROCREW_EXPORTED_REQUESTS_CA_BUNDLE, each holding
the value _export_ca_bundle wrote into that variable, and each published only when the
call assigned the variable — REQUESTS_CA_BUNDLE is only defaulted, so an operator's
value found there gets no marker, not even when it equals the bundle this install derives
(an operator who pinned REQUESTS_CA_BUNDLE to $(python -m certifi) of this very
install; one path marker shared by both variables would have vouched for theirs too).
_inherited_export_reason is the one classifier, and it answers yes in exactly one case:
the variable equals its own marker. A successor inherits a variable and its marker
together, so it reads its predecessor's export as what it is; an operator sets the
variable alone, so theirs never matches. Nothing else is provenance — not the path's
shape, and not the directory it lies in, Kiro Crew's own install trees included. An
operator who set SSL_CERT_FILE to a certifi bundle of their own ($(python -m certifi),
or one they appended a private CA to) holds a working policy while the file exists and a
fail-closed one once it does not — every handshake fails until they repair the pin, as
they chose; an operator can place a restricted bundle inside this runtime's own venv, and
a tree the installers delete takes that pin with it, leaving a fail-closed state that is
theirs rather than a stale export to re-derive over; and on macOS an explicit bundle is
also an exclusion (it bypasses the Security.framework injection, so the Keychain's CAs are
not trusted). Re-deriving over any of these would widen trust past what the operator
chose, so the prelude infers nothing from a path. It reads no data home and does not load
the config package or the update engine; the test file pins its import set at kiro_crew
and kiro_crew._ssl_compat, the same on every platform.
The one value this leaves unrecognised, by design, is a predecessor's export from before
the provenance existed: it reads as an operator's and is kept. While its file exists it
works (the managed-venv update engine keeps the current tree and the previous one, so a
predecessor's bundle survives one update and is pruned after the next); once that tree is gone the successor fails closed, and the
existing missing-file WARNING names the file and the way out — "if an earlier Kiro Crew
install exported this value, start it from a clean environment". The producing case is
narrow and one-time: an installer re-run deletes the retired <data home>/venv under a
running gateway (cli.sh retires it without stopping the service), and the operator then
uses the in-app restart rather than a service restart. One clean start heals the lineage
for good, because this runtime publishes the provenance and every later restart is
recognised.
A runtime value in either variable is dropped before the operator check (so a stale
REQUESTS_CA_BUNDLE beside an operator's SSL_CERT_FILE does not survive either), the
inherited provenance is dropped with it, and trust is derived for this install in the
clean-start order above, so a successor behaves exactly as a fresh start on the same host
would: the system bundle wins where there is one, the same install re-exports the same
path with nothing logged, both entry points running the prelude in one process see their
own export and keep it silently, and an operator's REQUESTS_CA_BUNDLE beside the
runtime's SSL_CERT_FILE survives the restart untouched. One WARNING line names each
value that changed and the reason it was judged the runtime's — WARNING rather than INFO,
because this runs in the prelude before logging is configured and the last-resort handler
drops everything below WARNING. LLAMA_CPP_LIB_PATH answers that same constraint the
other way round: its prelude records the removal silently, and the embedding loader emits
the one INFO line later, once logging is in place. Not on Windows: the prelude
exports nothing there, so no Kiro Crew process can have left a value behind, and whatever
is set is an operator's. test/test_ssl_certs.py::TestInheritedInstallPinnedBundle pins
the rule, including the two-bootstrap restart with the first run's environment carried
into the second against a pruned bundle, a dead pin without provenance kept even inside a
former install tree (with the clean-environment clause in its warning), an operator's
REQUESTS_CA_BUNDLE at the derived path kept across an upgrade restart while the
runtime's SSL_CERT_FILE beside it is re-derived, the two-module import set of the
prelude, and the operator's certifi pin on macOS that keeps its exclusion.
platform_log_append.append_line owns the decision log's filesystem transaction.
The configured home is resolved once as the trusted anchor; the immediate log
subdirectory and daily file are never resolved through links. POSIX pins the
anchor with pinned_fs.pin_parent, creates the directory relative to that pin,
and opens the directory and leaf with no-follow flags. Windows opens the resolved
anchor and the log directory with FILE_LIST_DIRECTORY access and read-only
sharing (attribute-only access takes no part in Windows sharing, so it would pin
nothing), rejecting reparse attributes on both, so a data-write or delete open of
either directory is a sharing violation while the append runs. The leaf uses
CreateFileW read/write, open-or-create, without following reparse points, and
its GetFinalPathNameByHandleW path must equal the pinned directory plus the
leaf name; a swap that landed before the pins is refused rather than written
through. Every native handle or descriptor is closed on failure as well as success.
Fresh POSIX directories/files request 0700/0600; existing modes are untouched.
The leaf is created with O_CREAT | O_EXCL. If another creator won or the file
already exists, one non-creating open uses the same pinned directory and retains
O_NOFOLLOW, O_APPEND and O_NONBLOCK. This avoids Darwin's concurrent
nonexclusive-create ENOENT without re-resolving the parent or following a
swapped link. A leaf that disappears between that EEXIST and the open is one
more lost interleaving: the existing bounded create-directory retry runs the whole
pinned sequence again, so the record is still written, through the same exclusive
no-follow create, under the same resolved anchor. Each failed attempt closes its
descriptors. Exhaustion raises FileNotFoundError naming the full path.
Other open errors propagate. Windows keeps its native open-or-create path.
Windows uses inherited ACLs, not a claim that POSIX mode bits enforce privacy.
The open file must be regular and have exactly one hard link. The existing
cross-platform file lock spans EOF validation, short-write/EINTR retries and
rollback. File offsets are explicitly reset inside the lock, including on Windows.
Lock acquisition and retries share a finite deadline that starts once the log is
open, so the create-and-pin ahead of it never spends the budget it cannot be
cancelled by. The OPEN carries a second budget of the same length, spent only on
Windows and only on ERROR_SHARING_VIOLATION: another process holding a transient
handle with narrower sharing than the access asked for is what contention looks
like there before the lock is reached, so the open is retried for that one error
while the budget lasts and reports it unchanged afterwards. Two budgets rather
than one because a slow open must not reach the lock with nothing left; the retry
covers the open alone, so no partial write is ever replayed. No additional worker
is spawned; a stalled filesystem syscall itself is not cancellable by either
deadline.
A DELETE meets the same transient hold. When pod down removes a pod's Task
Scheduler .cmd wrapper, the pod's own processes are already drained, but a
process the backend does not own (the Task Scheduler service finishing with the
action file, an indexer or AV scanner) can still have it open, and the delete
fails with [WinError 32]. pod.windows._unlink_waiting_out_sharing retries that
one error under a bounded deadline and re-raises it unchanged once the deadline
passes, so a real leak still fails closed; every other error raises at once. The
startup rollback of a cancelled pod up deletes the same wrapper through the same
helper. A teardown that deletes a file another process may have just used follows
the same rule: retry ERROR_SHARING_VIOLATION only, with a deadline, never any
PermissionError.
On write failure, rollback removes only the bytes counted for that append when the file has exactly the expected size. Existing bytes or unrelated growth are never truncated. A pre-existing torn tail, including one left by failed rollback or process death, is terminated with a newline before the next record is written, so one torn row costs one unparseable line and never joins the record after it. This is best-effort observation, not a durable journal: no fsync or crash-atomic publication is promised. POSIX locks serialize cooperating writers, not arbitrary same-user mutations or hostile filesystem mounts. Descriptor pinning prevents redirected opens, not POSIX rename of an already-open inode outside its original directory.
The retention sweep reuses the same pin: pinned_log_dir yields the no-follow directory descriptor on POSIX (names are listed with scandir(fd) and removed with unlink(name, dir_fd=...)) and holds the directory handle on Windows, so a swapped directory link cannot redirect a deletion. The decision caller catches append failures and warns without failing its turn.
test/test_platform_log_append.py exercises ordinary appends on every platform,
link refusal, short writes, rollback, concurrent writers, deadlines and cleanup.
Native Windows cases also require rename and directory-write-handle exclusion,
refusal of a redirected leaf handle, and release after failed CRT handle
conversion; Linux simulations do not verify these.
Embedding cancellation uses threading.Event and monotonic deadlines on all
supported platforms. It cancels queued work, not a running native inference.
Executor admission follows the underlying future's completion, never the
cancelled asyncio waiter's lifetime. Cache stripes and dispatch locks never
cover native inference; store alignment holds only Python locks and performs
no model load or inference.
An open Windows process handle pins its process object and prevents PID reuse even
through exit; reuse is possible only after exit and the last handle closes
(Windows process-object lifetime).
Exact-handle tree discovery retains root/descendant handles through its scans;
retained PIDs cannot hide a replacement while their handles remain open.
Host-effect tests must attempt authoritative teardown in finally; OS refusal or
incomplete identity proof must fail loudly and preserve isolated HOME/service
evidence, never certify zero residue or invoke an unsafe duplicate cleanup authority.
Service-free, newly owned precondition cleanup is a separate case.
windows.stop requires a boot-contained Job descriptor or a generation-bound
kernel-zero receipt. The CLI reserves the run before scheduling; the supervisor
claims it under a separate short lock, assigns the initial child while suspended,
and atomically publishes its exact identities before resume. A legacy PID record,
marker, HOME or task without that protocol refuses reclamation.
Before /End, stop opens the existing Job and pins its publisher and available
initial process by exact identity. Access/query failures never mean death. After
retiring the publisher it requires a successful Job zero-count query and persists
a receipt. A publisher may also publish that receipt as its final action after
draining, with no further child creation or resume. Receipt consumers still retire
the publisher before cleanup. The receipt survives task-deletion, sidecar-deletion
or HOME-cleanup failure. Authoritative teardown must delete the handoff marker,
PID record and result sidecar successfully before consuming the receipt after the
full seven-sweep HOME cleanup. A retry uses the same generation's receipt even if
the Job has disappeared; supervisor-side diagnostic cleanup remains best-effort.
This covers unobserved restart branches without reconstructing dead intermediaries;
marker/PID record removal and polling history do not authorize reclamation.
descendant_termination_handles checks every first-snapshot edge against exact
handle creation/exit times, then rechecks identity and lifetime bounds after a
second snapshot. If an observed intermediary exits and disappears from Toolhelp,
its pinned handle preserves the first edge only when the second identity read
confirms the same PID/creation time and a published exit time. A surviving child's
PPID must still agree; its creation time must precede that intermediary's exit.
Changed parent links and positively disproven identities/lifetimes are excluded.
Unknown is not an exclusion: an unopenable candidate must be absent from a fresh,
successful full process snapshot, or be positively disproven by creation order,
or discovery raises OSError. Creation order disproves descent because a
descendant is created after the root it descends from: a chain node whose process
already existed before the root holds a recycled PID naming an unrelated process,
so it disqualifies itself and every observed PID whose only ancestry route to the
root runs through it, including a descendant whose own termination handle opened
successfully -- those handles are closed before discovery returns. That instant is
read through a validated query-only handle, which answers where a termination
handle is refused; a node already pinned by a handle is read from that handle
instead, whose object cannot have been recycled. The drop is abandoned wholesale,
and discovery raises, when any disqualified PID is a retained identity: dropping
it would discard authority an earlier scan already proved. Creation order
disproves nothing, and discovery raises, when the instant is unreadable, when the
query-only handle is itself refused, or when the instant is at or after the
root's. Absence alone
is insufficient when that same fresh snapshot contains an entry referencing the
observed, now-vanished unopened parent: discovery refuses even if the child and
its descendants first appeared after the initial snapshot. The one exception is a
referencing entry whose own creation instant predates the root: an orphan that
already existed before the root names an earlier holder of the recycled PID, not
the vanished candidate, so it neither blocks discovery nor joins the tree. Such
an orphan was already listed under the same parent by the initial snapshot, so
any other entry refuses without a query. Its children are strangers too, and
their handles are closed with the orphan's, but only when each of its children in
either snapshot is pinned by a termination handle opened in the same call, is
still listed under the orphan by the fresh snapshot, and has no child of its own
in either snapshot: an unpinned PID may hold a new process by the fresh
snapshot, a PID reused before its handle opened shows a different parent there,
and a grandchild's parent PID may have been recycled from a process of the tree.
Otherwise the referencing entry refuses. A console host that exits before its
handle opens leaves exactly this shape when its PID was recycled from a process
whose children outlived it. This exception is deliberately narrower than the
creation-order disproof above, which drops a disproven node's whole numeric
subtree. Skipping this refusal is sound only one level below a process proven
older than the root, and only for children pinned as described, so the two rules
must not be merged. This guard reports
only a total and at most three child/parent PID pairs, takes no extra snapshot,
and grants no identity or termination authority. A vanished unopened child with
no fresh descendant reference remains admissible.
A false pid_exists result is not sufficient because query denial can produce it too.
Unreadable opened/retained identities, missing live objects, and a surviving
child whose vanished unpinned parent has no lifetime proof also raise, so callers
must preserve HOME/task state rather than certify a partial tree as drained.
For an unopenable candidate still present in the fresh snapshot, the refusal
includes failure-only diagnostics for at most three candidates and eight PIDs
per first/fresh ancestry chain. The opener captures the immediate native error
(or Python exception type only); the report includes the root identity at scan
start and current identity/lifetime observations from already-pinned relevant
handles. A separate query-only handle may observe the candidate for this report,
but is always closed and is explicitly unvalidated: no diagnostic observation
changes the refusal or provides kill authority, which is why the creation-order
disproof above is a distinct validated read taken before the refusal is decided.
Diagnostic failures leave the original refusal intact.
No command lines, environment, file contents, or unrelated process inventory
are emitted, and successful discovery does not collect or log this report.
All newly opened handles are closed on failure, including failures partway through
opening candidates; root and retained handles remain caller-owned. Positively
rejected newly opened handles are closed before returning the proven subset.
This covers an already observed, handle-pinned chain. An intermediary that died
before it was ever observed/pinned remains unverifiable; a single numeric snapshot
is not enough to recover that chain. The deterministic and self-owned native
regressions are in test/test_platform_compat_process_tree.py, TestProcessDescendants.
Windows physical ACP starts reserve cleanup bookkeeping atomically before the
spawn await, across threads and event loops. Both transports use the same
process-wide admission set: _WINDOWS_CLEANUP_ROOT_LIMIT is 64 physical trees,
including starting, live, failed and manually quarantined trees. This is a separate
internal cleanup limit, not a change to pool, RSS, Job or timeout configuration.
A live tree keeps its reservation, so simultaneous failures cannot exhaust the
space needed to retain already-admitted roots. A cancelled launch settles its
spawn task and takes ownership of any returned child before attempting cleanup;
only an empty failed-launch reservation or a verified retired tree is refunded.
The suspended-resume worker also settles before cancellation initiates teardown.
The Windows factory capture boundary is the successful native CreateProcess
return, before CPython closes child-side pipe descriptors, publishes the Popen
handle, closes the initial thread handle, registers the process wait, or connects
async pipes. The cleanup reservation receives the exact native process handle
there; CPython and cleanup then share one reference-counted subprocess.Handle.
A post-creation exception publishes this owner for maintenance even without a
returned asyncio Process. Pre-creation exceptions refund the empty reservation.
The initial thread handle also has a per-call reference-counted owner so an early
pipe-descriptor failure cannot skip its release.
The reservation's exact handle is recorded before the tree's identity is read, and
that read runs on subprocess_executor() rather than the starting loop. The read
polls for an exit FILETIME the kernel publishes slightly after it reports the exit,
so a child that dies the moment it resumes makes it wait tenths of a second — on a
loop that is serving every other session. Recording the handle first is what makes
the hop safe: a cancellation arriving during the read still leaves this exact child
retained for maintenance instead of dropping it.
This narrowly reuses CPython functions with per-call substituted global bindings;
it does not replace asyncio/Popen globals or install methods on the live loop.
Only the standard CPython Proactor subprocess implementation is admitted; a
different loop implementation refuses before creation. The admission reads private
CPython shapes, so it is version-coupled and the coupling is measured rather than
assumed: the shipped predicate and its capture were exercised against a real child
process on stock Windows CPython 3.12, 3.13 and 3.14 — every minor requires-python = ">=3.12" admits that exists to measure — and a non-Proactor loop was refused in
the same run. requires-python carries no upper bound, so a later minor is
unmeasured by construction: it either satisfies the predicate or refuses every
tracked Windows start rather than capturing nothing silently, which is the intended
direction of failure. Both refusals name the measured interpreters, so the remedy
reaches the operator without this file; re-running that measurement is the gate for
adopting a new minor, and the committed form of it is
test/test_runtime_cleanup_windows.py::test_native_admission_and_owner_shutdown_refund_after_verified_drain,
which spawns a real admitted tree through this capture on whichever interpreter is
running. It runs on the Windows CI shards, so a minor that reshapes these internals
turns the adoption question into a failing check rather than an archaeology exercise.
POSIX and untracked
Windows launches retain their original path. This is in-process ownership, not
protection against gateway death, interpreter failure or resource exhaustion
inside the native call/capture itself.
_WINDOWS_CLEANUP_IDENTITY_LIMIT is 4096 exact objects per tree (root included),
shared by retained handles, signalled identities and terminal-scan identities.
This gives generous build/browser fan-out headroom while bounding retention per
tree; the number of trees is separately bounded by the root reservation cap, so
the aggregate follows from those two named limits rather than a figure recorded
here that would drift when either constant moves. These are engineering
bookkeeping ceilings, not measurements of maximum workload size. Discovery checks
the retained/candidate union before opening new child handles. Its breadth-first
candidate stores share that limit. Toolhelp's unrelated-host input is separately
bounded at _WINDOWS_CLEANUP_SNAPSHOT_LIMIT (65536 entries) during enumeration,
not after allocating the complete process table. Snapshot overflow is incomplete
evidence, never an empty tree. Temporary unvalidated candidate handles are closed
on discovery failure; previously owned root/intermediary pins remain retained.
Any identity/snapshot overflow permanently marks the tree
manual-handling-required in this gateway process. It keeps its pins and tracking,
receives no automatic refund and is excluded from retries. A later shorter
snapshot cannot clear the mark. New Windows physical starts are refused while
any such mark exists; other already-admitted trees remain owned and can drain.
The transition emits an error with the root PID and retained count. This is
bookkeeping quarantine, not OS isolation: unobserved descendants may still
run. No API, eviction rule or successful numeric PID probe clears the condition.
Ordinary transient failures without overflow continue to retry automatically.
Operator recovery is manual: preserve the diagnostics and tracking, stop creating new work, and use independently verified process ownership to account for and stop the affected workload, including descendants not represented by the retained pins. Do not kill a process merely because it reused a logged PID. If complete ownership/absence cannot be established, a planned host reboot is the reliable way to end surviving processes (save unrelated work first). Restart the gateway only after that independent cleanup or host restart. A gateway restart alone neither terminates all descendants nor proves they are gone; it loses this process-local quarantine and its pins. Deleting tracking files is not recovery.
ACP runtime and direct-client teardown retain the original asyncio process
object and drain it through terminate_windows_asyncio_tree. The Windows
kill_process_tree_pinned path uses the same terminate_windows_process_tree_owned
operation after confirming the recorded creation identity. Neither path relies
on a still-running root PID or a successful taskkill return code.
The bounded worker discovers descendants through exact handles, terminates each
verified object and scans each parent again after confirmed exit. A successful
pass closes every acquired handle. A failed pass from an owning caller transfers
the original root and every already observed intermediary handle into
process-local pending state keyed by the exact root incarnation; it retains no
provider or client object. Repeated transfers deduplicate and close only the
redundant root handle. The existing off-loop
session_pid.cleanup_orphaned_session_roots maintenance entry advances a finite,
fair snapshot of that state before its ordinary PID-file orphan scan; a tree
already draining on another caller is skipped with a non-blocking lock and
rotated behind its peers, so one busy entry cannot hold up the sweep (caller-
initiated cleanup keeps its blocking serialization). A denied
tree remains retained and visible and moves behind its peers; only an
exact-handle-verified complete drain retires the state. On completion, a
synchronous maintenance callback retires the session layer's PID-file records
and protected-PID shield WHILE the state lock is held and the exact root handle
still pins the incarnation, BEFORE any handle is closed — so a recycled pid
cannot register fresh tracking between the close and the untrack. The handles are
closed only after that callback succeeds; a transient callback/write failure
leaves the state un-retired with its handles open, so its receipt survives for
the next tick rather than being lost, and an in-flight duplicate owner that has
already completed the same state contributes no second retirement. This is
same-process retry continuity, not crash recovery: the
maintenance path never reconstructs a missing original handle or gains cleanup
authority from a PID, a PID-file entry, or a successful TerminateProcess
return. Phase-one periodic PID identification remains non-destructive.
Caller cancellation is delivered after its current cleanup attempt settles. Unknown identity/ancestry, denied access or a non-draining tree is a failure, not an empty tree; ACP retains the original process and PID tracking when the owning call does not complete, while the transferred exact handles remain independently retryable after provider/client references are dropped.
A pass that runs out of its bounded budget (_WINDOWS_TREE_REAP_TIMEOUT_SECS)
before every member is confirmed raises WindowsTreeDrainPending. Members
discovered too late in the pass to be signalled count as pending too. It is an
OSError, so every caller that treats an unconfirmed drain as a failed kill keeps
doing so. It names the root and the number of members still pending. The tree is
not lost: its pins stay in the pending state, and the maintenance sweep resumes the
drain from the members already confirmed. A slow host meets this routinely,
because each member's pass costs two identity reads and two Toolhelp snapshots.
AcpRuntime therefore logs it as one WARNING line, not a traceback, and still
raises. A failed kiro session setup logs its original failure at WARNING before the
cleanup kill, redacted and folded to one bounded printable line, because that text
can come from the backend. Without that line, the cleanup's own output would be
the only trace of a repeating setup failure.
This does not reconstruct an intermediary that exited before any available
handle observed it, and the completeness a successful drain asserts is therefore
scoped to the members it retains: the pinned root plus every descendant some
snapshot reached through a still-certifiable chain. An ancestry chain that IS
observed but cannot be certified raises rather than certifying a subset — that
much is a refusal, never permission to signal numeric PIDs. A live grandchild
whose only edge to the root ran through an intermediary that exited before the
first scan is a different case and must not be read as covered by that refusal:
Toolhelp reports its parent as a vanished PID, so no walk from the root reaches
it, the drain confirms the exits it can see and reports success, and that
residue falls to the PID-file orphan sweep. Pinning at spawn closes the window
for the ROOT; it does not pin an intermediary nobody has seen yet. POSIX teardown and Windows resource Job limits are
unchanged. Native small-process regressions live in
test/test_runtime_cleanup_windows.py; deterministic timing/error contracts
live in test/test_windows_tree_reap.py.
Reading a handle's identity has two callers with different needs, and the split
is load-bearing. A drain must certify that a member exited, so it asks for the
exit bound and accepts a short poll while the kernel publishes the exit
FILETIME. get_process_start_id answers a narrower question — which process
object a PID names — and publishes itself as non-blocking and safe to call
directly from the event loop, so its Windows arm asks for the creation half
alone: no liveness wait, no poll, and no sleep on a coroutine's thread. The
creation FILETIME is the whole identity, so answering without the exit half
costs the caller nothing.
TerminateProcess answers a process whose exit has begun with
ERROR_ACCESS_DENIED, the same code a genuine refusal carries, and a drain meets
that routinely: every member started with CREATE_NO_WINDOW owns a conhost.exe
that Toolhelp lists as its child, and that console host exits on its own once its
client is killed, so it can leave between the liveness read and the terminate. The
refusal can arrive before the object signals: an exit publishes the exit code, then
runs the process down (the terminate is refused from there on), and only then
signals the object. terminate_process_handle therefore reads that refusal as an
exit, and returns False as it does for any member that had already exited, when
GetExitCodeProcess no longer answers STILL_ACTIVE (a running process always
does), or when the object signals within a bounded wait
(_WINDOWS_TERMINATE_REFUSAL_WAIT_MS, a zero-time look on the event loop), which
covers a process whose exit code is 259. A refusal neither settles stays an
OSError: a genuine refusal of a process still running after that wait, or one on a
handle that cannot be waited on while its exit code reads STILL_ACTIVE. So does any
other error. Real-process regressions force both interleavings:
test/test_runtime_cleanup_windows.py::test_a_member_exiting_inside_the_terminate_window_reads_as_exited
and test/test_runtime_cleanup_windows.py::test_a_member_refused_before_its_object_signals_reads_as_exited;
test/test_platform_compat_windows_tree.py::TestTerminateRefusedOnAnExitingMember pins each
branch on a virtual clock. pod._windows_job.retire_identity meets the same refusal
when it ends a pod publisher, and judges it by its own bounded retirement wait.
Teardown deliberately does not keep a Job handle and call TerminateJobObject
instead of draining exact handles. The Job that apply_job_limits creates is
anonymous and is closed before that function returns, so there is no handle to
retain and no name to reopen; KILL_ON_JOB_CLOSE is left unset on purpose,
because setting it would tie an agent tree's LIFETIME to a resource ceiling's
handle. That ceiling is also fail-soft by published contract — a missing Job must
not fail a spawn, and four Win32 call sites log and continue — so making
reclamation depend on it would either turn every ceiling failure into a refused
start or leave exactly the degraded host with no reclamation at all. A Job also
enforces by REFUSING new members rather than killing existing ones, so a
saturated Job is a state the gateway must survive, not a teardown primitive.
pod._windows_job.PodJob owns pod-specific named Windows Job handles. Creation
uses a unique global name and an owner-only protected DACL, so the scheduler and
CLI can run in different Windows sessions; opening an
existing job never creates one. Assignment borrows the caller's original process
handle and requires a never-resumed CREATE_SUSPENDED child. Breakaway and
kill-on-close flags are refused. Membership and accounting errors raise rather
than reporting absence; termination succeeds only after a bounded kernel zero
count. Closing a handle does not terminate members. The shared resource-ceiling
helper and its configuration are unchanged.
The Task Scheduler backend uses these primitives with pod._windows_run durable
run identities and publisher retirement. Job emptiness alone is not reclamation
authority. Before attempting /Run, a failed start may cancel only its exact
unclaimed reservation under the claim lock. The durable cancelled
state refuses admission and survives task/wrapper/result cleanup errors; the next
start retries that cleanup before reserving a new generation. The claim lock
covers cancellation through receipt deletion. Claimed, malformed or changed-run
records and unexpected HOME/PID/handoff evidence refuse rollback. A failed or
raised /Run never grants cancellation, even if no publisher has claimed yet.
If cancellation itself cannot be persisted, the ordinary reservation remains
unresolved rather than being inferred safe on a later invocation.
The scheduled pod _run producer claims its reservation as its first act,
before the checkout, venv and dist checks, so the record (preparing) names it
by pid plus creation time. A producer whose own claim is refused writes nothing.
On every exit of a claimed boot the producer, not the task wrapper, writes
.winresult; the wrapper writes no sidecar. A boot that refuses without
spawning a gateway then publishes a finished receipt with its exit code,
under the claim lock and only over its own unchanged preparing record. An
escaped exception or an unproven Job drain withholds that receipt and leaves
preparing. finished certifies that no gateway was spawned; it does not
cover a descendant of a process started before any lifetime Job existed (the
child-viability probe), the same residual the ready path accepts.
stop retires an unspawned (preparing or finished) generation only after
proving its producer gone. It opens the producer by pid and creation identity
(a recycled pid reads as gone and is never signalled) and refuses to retire its
own pid. A preparing producer is only waited for, never terminated: stop
refuses at its deadline. A finished producer is given the whole stop budget
through wait_identity to exit on its own, because the boot's failure audit is
written after the receipt, and is terminated only if it outlives that budget.
After the wait, stop re-reads the record and refuses unless the generation and
publisher are unchanged and the state is still unspawned. Then /End stops any
wrapper still unwinding. A supervised-pid record or handoff marker refuses, as
does a HOME under a preparing producer; an evidence path that cannot be
inspected counts as present. Only then is retired published, as a
compare-and-swap under the claim lock. finish consumes drained or retired
only once HOME is gone, so a HOME cleanup failure stays retryable. A reserved
record nobody claimed, and a preparing record whose dead producer left a HOME,
still need the manual retirement in pod/README.md.
Native tests exercise owner-only access, descendant containment,
nested resource jobs and breakaway refusal; injected failures run on all hosts.
rename_noreplace uses the Linux libc wrapper when available. On older glibc
without that symbol, it uses the same kernel operation through syscall with
an architecture-specific number. Unknown architectures remain unsupported,
and an occupied destination still refuses atomically. The fallback does not
replace the operation with a check-then-rename sequence.
CI holds all three platforms at the UNIT layer: the backend-test shards cover
Linux, backend-test-windows covers Windows, and backend-test-macos covers
macOS. All three run the whole suite, so a POSIX call that only works on Linux
goes red on the macOS shards rather than shipping — but the macOS shards are
NIGHTLY (platform-tests.yml, called by nightly.yml), not per-pull-request: a
macos-15 runner took 176-213 minutes to arrive on the PR path, which is ~64% of a
pull request's CI wall clock, and the queue sat on the required check. So a
POSIX-but-not-Linux regression is caught within a day and before any nightly bytes
are published, rather than before merge. In front of a pull request there is
macos-on-demand.yml (the same full suite, called against the PR head, advisory;
runs on a darwin-sensitive path, on the ci:macos label, on a 1-in-50 SHA sample, or when an added
*.py/*.sh line uses a Linux-only primitive such as /proc/ or GNU stat -c; the path, sample and
content switches are refused while the lane already holds LANE_MAX_LIVE_RUNS live runs of the hosted
macOS pool (the ceiling moves with the shard count, so the value lives in the workflow), the
label never is) and the static side of
this table. A shard passing is still not
evidence that a gateway starts: files listed in
test/windows-collect-ignore.txt are excluded on Windows, with further node ids in
test/windows-expected-failures.txt and test/macos-expected-failures.txt.
What runs a real gateway on macOS and Windows is ci.yml's e2e-boot-matrix
job (test/e2e/test_gateway_boot_matrix.py), which boots one per test against
the packaged fake ACP backend and asserts a completed prompt turn. Point a
process or signal change at that job, not only at the shards. See
../../ci/e2e-gate.md.
Still run process, signal, file-lock and metrics changes on macOS and Linux locally where you can. A test that only ever runs on the author's platform is how a silent no-op ships, and a CI red found after the push costs a round trip.
A test that cannot pass on macOS gets a precise
skipif(sys.platform == "darwin", reason=...) naming the capability, or its node
id in test/macos-expected-failures.txt, the burn-down list applied by the
rootdir conftest.py, same mechanism as windows-expected-failures.txt. Never
widen a platform assertion to make a red go away.
Frontend support is Chrome, Firefox, Safari and Edge, using standard Web APIs and
guarding the rest (typeof Notification !== 'undefined').