Repository navigation
Add macOS assigned-process-group containment for Watcher detectors - #257
Conversation
Implement the macOS guard for trusted non-detaching detectors (#172, ADR 0054 as amended by ADR 0057). - A private per-attempt guard runs in its own session and forks a gated trampoline that becomes the process-group leader. The detector execs only after the runtime durably records the full identity (boot-session UUID, guard and leader PID and start time, PGID, nonce, receipt path). - The guard keeps the leader unreaped through every nonzero group signal. Completion needs a fresh nonreaping waitid plus a two-slot proc_listpids census showing only the leader. Signal authority is then consumed before the exact reap, and only kill(-PGID, 0) == ESRCH lets the guard write and sync the Ended receipt. - Admission is capability and safety checks only (native arm64/x86_64, not Rosetta-translated, release kernel, probes on the gated leader). The OS version is never an admission input. - The guard restores default SIGCHLD handling and closes inherited descriptors at startup. An escaped process still holding the output pipes after the group ended fails the attempt after a bounded drain. - Enable the existing process tests on macOS and add a native conformance suite, fixture modes and a hosted macOS CI job. - Describe the capability in the runtime and design docs. The runtime matrix tests stay disabled on macOS: the bootstrapped daemon connection used by senders is not supported there yet. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
|
Design steward (Watcher workstream): acceptance boundary for this PR. Implementation and design review at the exact head will follow in a separate comment. This PR is the single #172 product PR, so
Answer to the question in the body: #172 cannot close while macOS senders are unready. The daemon's mapped bootstrap identity on macOS is a real prerequisite outside containment. It is being classified with the Local daemon lane. It will either be absorbed here or land as its own upstream item, with #172 depending on it. Either way, this PR becomes acceptable only once senders are ready and parity passes at its head. Other points from the body:
Acceptance is not changed: no kernel, finite-run or exact-build gate returns, and no per-run grant is needed for ordinary CI. Campaign runs the merge gate. |
|
Addendum to the steward boundary above, at df1437a: the ApplicationClient consumer disposition for this PR is UNSATISFIED. Before an effective
Disabled tests and containment-only evidence do not substitute. This is the same requirement as acceptance item 3, now also confirmed by the consumer. Local daemon ownership of the mapped-image/bootstrap prerequisite is unchanged. |
|
Design steward: implementation and design review of PR #257 at exact head df1437a (base b0d63db). Verdict: CHANGES REQUIRED. This covers acceptance item 2 for the #172 product PR, reviewed against operator decision 6830371292 as amended by 6835298564, ADR 0054 as amended by ADR 0057, and the #172 body. It is not a merge approval; Campaign runs the merge gate. Method: steward design pass plus one independent static implementation review, both read-only at this exact head (diff, head files, hosted CI logs). Nothing was built or run. XNU semantics are from documentation and memory, not a new kernel audit. Containment core: conformsNo violation of the containment invariants was found.
BlockingB1. Native conformance has produced no evidence.
B2. A leaked control descriptor can disable runtime-death cleanup.
B3. Docs must not move sender readiness out of #172.
Acceptance prerequisite (steward boundary and consumer addendum above)
Non-blocking (fix, or record as a known limitation in
|
lossyrob
left a comment
There was a problem hiding this comment.
CHANGES REQUIRED at df1437a.
Publishing the existing complete steward review from #257 (comment) as a submitted PR review. The findings below retain their original exact-head scope and static-review limitations; this is not a new audit or native execution. GitHub does not permit a formal request-changes review on one's own PR, so this is submitted as COMMENT; the technical verdict remains CHANGES REQUIRED, with no acceptance or merge approval.
Integration correction: the original final instruction to "rebase" is superseded by Campaign's ordinary-merge/no-rebase policy. After #255 merges, integrate current main with an ordinary merge while preserving its owned ADR 0057 changes. The CI discussion below describes the original reviewed head, not a fresh claim about upstream #258. The operator is handling the separate #259 external Mac-worker handoff; no implementation assignment is inferred here.
Design steward: implementation and design review of PR #257 at exact head df1437a (base b0d63db). Verdict: CHANGES REQUIRED.
This covers acceptance item 2 for the #172 product PR, reviewed against operator decision 6830371292 as amended by 6835298564, ADR 0054 as amended by ADR 0057, and the #172 body. It is not a merge approval; Campaign runs the merge gate.
Method: steward design pass plus one independent static implementation review, both read-only at this exact head (diff, head files, hosted CI logs). Nothing was built or run. XNU semantics are from documentation and memory, not a new kernel audit.
Containment core: conforms
No violation of the containment invariants was found.
- Census:
int[2]PROC_PGRP_ONLY. Only a 4-byte result naming the leader passes. Errors, zero, malformed, saturated and mismatched results all fail. - Terminal check: a fresh zeroed
waitid(P_PID, WEXITED|WNOHANG|WNOWAIT)on every attempt. - Seal: the terminal-plus-census pair is taken twice.
Anchor -> Sealed -> FormerGroup; nonzero kill exists only onAnchor(kill_groupandDrop). The leader is reaped exactly, with a status consistency check. - Absence:
kill(-PGID,0). Only ESRCH is absent; 0 and EPERM are present. The receipt is written only after this, with create_new, sync_all, a link and a directory fsync. - Recovery: clears only on an exact identity-matched finalized receipt or a changed
kern.bootsessionuuid, otherwise Unproven. No numeric PID is ever signalled. - Admission:
proc_translatedENOENT and 0 are native; other values and errors are refused.- Hardware and process architecture are cross-checked.
- Non-
RELEASE_kernels are refused. - The OS version is never an input.
- The guard repeats admission and probes the gated leader.
- Refusal produces no receipt.
- Guard startup restores default SIGCHLD.
- Linux and Windows change only in cfg lists and the new
MacosGuardvariant.
Blocking
B1. Native conformance has produced no evidence.
- All three
Watcher containment conformancelegs (macos-15, macos-26, macos-15-intel) fail withstart process guard: No such file or directory. - Cause:
process_macos.rs:476-481finds the guard besidecurrent_exe(), dropping a trailingdepsdirectory. Hosted Cargo now runs test binaries fromtarget/debug/build/telex-watcher/<hash>/out/, so the guard is not there. - This fails closed, since no detector ran, but it means acceptance item 1 has no hosted evidence.
- Fix: give tests an override fed from
CARGO_BIN_EXE_watcher_process_guardas a test-only crate API, never an environment variable honoured in production. Or resolve the new layout. Do not change how production finds the guard beside the installed executable. - The
macos-26label does exist; that leg ran. - The Ubuntu and Postgres failures (
tests/support/telex_isolation.rs:56, "branch telex binary not found") come from the same layout change and also fail on main at b0d63db. They are not caused by this PR. Full CI must still be green at the head that is accepted.
B2. A leaked control descriptor can disable runtime-death cleanup.
- macOS has no
SOCK_CLOEXECorpipe2.UnixStream::pair()(process_macos.rs:468) and std's stdio pipes therefore set close-on-exec in a separate step, and std'sposix_spawndoes not usePOSIX_SPAWN_CLOEXEC_DEFAULT. - So a non-guard child that the runtime spawns at that moment can inherit the runtime end of
control. - If the runtime is then SIGKILLed or crashes, the guard never sees EOF. It has no independent timeout, so the detector runs unbounded until it exits by itself.
- That breaks two #172 outcomes: private runtime-liveness observation, and terminating the group on every cleanup path. Abrupt runtime death is one of those paths.
- This is not ADR 0057's accepted residual, so it cannot stay as a disclosure.
- Required: the guard must observe runtime death independently of descriptor EOF. For example:
- pass the runtime PID;
- check that
getppid()matches and is not 1; - register kqueue
EVFILT_PROC/NOTE_EXITon it, where ESRCH means the runtime is already dead; - re-check
getppid(); - treat runtime exit like EOF in the release and wait loops.
- Add a conformance case: runtime SIGKILL while a third-party process holds the control descriptor, and the group still Ends.
B3. Docs must not move sender readiness out of #172.
docs/design/watcher.md(~L733-736) says macOS is unshipped "until its packaging and sender path are accepted separately".docs/watcher-runtime.mdsays the bootstrapped daemon connection "is not yet supported there".- Sender readiness and SQLite/PostgreSQL parity are #172 acceptance item 3, not a separate acceptance. Release-archive packaging may remain separate.
- At the head that closes #172, these sentences must describe a working sender path and qualify only packaging and distribution.
- Until then, keep the #177 fail-closed sentence. The #172 body allows it to be removed only when the complete capability lands at that exact head.
Acceptance prerequisite (steward boundary and consumer addendum above)
- The sender path depends on upstream #259 (#259): macOS daemon/bootstrap mapped-identity support. Campaign has admitted it as a bounded Local item with #172 depending on it. Its owner is being arranged separately, not assigned to this PR.
- Once #259 lands, this PR needs, at its own head:
- a runnable macOS InstalledCurrent route;
- legitimate sender readiness;
- the macOS runtime-matrix and
installation.rslifecycle and health parity tests enabled and passing; - full CI green.
Closes #172stays. The PR cannot be accepted before then, and no reviewer option narrows that.
Non-blocking (fix, or record as a known limitation in docs/watcher-runtime.md)
- N1. If a leaked stdout or stderr write end is held by an unrelated process, a conforming detector hits the 2 s drain and is labelled nonconforming. Containment correctly stays Ended. If the detector inherits the guard's stdin, a leaked stdin write end can also hang an EOF-reading detector until its timeout. Moving pipe creation into the guard (passing the runtime ends back with SCM_RIGHTS) would fix both.
- N2.
descriptor_limit()clamps at 65,536 (process_macos.rs:799-801). Descriptors numbered above that survive the guard sweep and the trampoline close loop. Enumerate the open descriptors (PROC_PIDLISTFDS), or userlim_curand refuseRLIM_INFINITY. - After #255 (#254) merges, rebase. ADR 0057's admission text is owned there; do not edit it here.
Send a new exact head here once these are addressed. The re-review will cover only the changed parts and the acceptance gates, not the core again.
- Tests name the guard Cargo built through a test-only crate API; the installed runtime still finds the guard beside its own executable. - The guard watches the runtime process with kqueue NOTE_EXIT, so runtime death ends the attempt even when another process holds a leaked copy of the control endpoint. Adds a conformance case for that. - Descriptor sweeps enumerate open descriptors (PROC_PIDLISTFDS) instead of a clamped numeric range. - Docs keep the macOS fail-closed text until #172 lands with sender readiness and parity (#259), and record leaked pipe ends as a known limitation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pdate # Conflicts: # .github/workflows/ci.yml
Closes #172
macOS source builds now run trusted non-detaching Watcher detectors and send events through the identity-verified InstalledCurrent Rust client. This branch incorporates main through #260, including the macOS daemon bootstrap correction; sender readiness and SQLite/PostgreSQL lifecycle and health coverage are enabled here.
Implementation
Validation
Native Apple Silicon Mac: macOS 26.7.1 / 25G241, SDK 26.5.
Hosted validation at exact head
4d57063e5a5593f89010c471b11042eb571b9ab7is green: all 26 CI jobs and all 3 Windows archive jobs passed.Each hosted native job passed 10 containment unit checks, 25 process/conformance tests, the separately executed PID/PGID reuse stress test, 98 library tests including live PostgreSQL, 30 CLI tests, 13 installation tests and 3 diagnostic tests. PostgreSQL was required and executed; these are not skipped-backend passes. The actual runner set records coverage, not runtime admission policy. The prior Linux guardian-staging failure is fixed.
Limits
Detectors must remain in the assigned process group. ADR 0057's accepted transient-invisibility residual remains: Ended means the recorded predicate held, rather than a stronger descendant-containment claim. A leaked stdout/stderr pipe end can misclassify a conforming detector after the bounded drain; a leaked stdin write end can defer EOF until timeout. Runtime death is independently observed despite those leaks.
Release-archive packaging/distribution and production soak remain separate. This PR adds no privileged or persistent helper, entitlement, public guard endpoint, or version-number admission gate.