Merge FEATURE-ci-freebsd-pid-zero: Accept the kernel process during cleanup

Author: etr

scripts/lib/package_commands.py

@@ -267,7 +267,8 @@ def _process_snapshot(deadline):
                 or any(flag not in '+<>ACEJLNSsVWX' for flag in fields[3][1:])):
             raise RuntimeError('malformed command process snapshot')
         pid, parent, group = map(int, fields[:3])
-        if pid <= 0 or pid in members:
+        # FreeBSD exposes kernel PID 0 in parent/group 0; it is observation only.
+        if pid in members or (pid == 0 and (parent != 0 or group != 0)):
             raise RuntimeError('invalid command process snapshot PID')
         members[pid] = (parent, group, fields[3][0])
     if not members:

scripts/test-v3-installed-consumer.py

@@ -604,6 +604,50 @@ def launch(argv, *args, **kwargs):
             return popen(argv, *args, **kwargs)
         return patch.object(subprocess, 'Popen', launch)
 
+    @unittest.skipUnless(os.name == 'posix', 'FreeBSD kernel process observation')
+    def test_ps_kernel_pid_zero_preserves_owned_leader_and_live_descendant(self):
+        data = '0 0 0 DLs\n2255 2178 2255 Z\n2258 2255 2255 S\n'
+        with patch.object(sys, 'platform', 'freebsd14'), self.ps_output(data):
+            members = commands._process_snapshot(time.monotonic() + 2)
+        self.assertEqual({0: (0, 0, 'D'), 2255: (2178, 2255, 'Z'),
+                          2258: (2255, 2255, 'S')}, members)
+
+    @unittest.skipUnless(os.name == 'posix', 'FreeBSD kernel process validation')
+    def test_ps_kernel_pid_zero_keeps_snapshot_validation_fail_closed(self):
+        for data in ('', '0 0 0 DLs\n0 0 0 DLs', '0 1 0 DLs', '0 0 1 DLs',
+                     '-1 0 0 DLs', '0 -1 0 DLs', '0 0 -1 DLs',
+                     '0 0 0 !', '0 0 0 DQ', '0 0 DLs', '0 0 0 DLs command'):
+            with self.subTest(data=data):
+                with patch.object(sys, 'platform', 'freebsd14'), self.ps_output(data):
+                    with self.assertRaisesRegex(RuntimeError, 'snapshot'):
+                        commands._process_snapshot(time.monotonic() + 2)
+
+    @unittest.skipUnless(os.name == 'posix', 'FreeBSD kernel row during real group cleanup')
+    def test_ps_kernel_pid_zero_does_not_prevent_owned_descendant_retirement(self):
+        popen, killpg = subprocess.Popen, os.killpg
+        groups = []
+        def launch(argv, *args, **kwargs):
+            if argv[0] in ('/bin/ps', '/usr/bin/ps'):
+                code = ("import subprocess,sys; "
+                        f"data=subprocess.check_output({argv!r}); "
+                        "kernel=any(line.split()[0] == b'0' for line in data.splitlines()); "
+                        "sys.stdout.buffer.write((b'' if kernel else b'0 0 0 DLs\\n') + data)")
+                argv = self.command(code)
+            return popen(argv, *args, **kwargs)
+        def signal_group(group, sig):
+            self.assertGreater(group, 0, 'kernel PID/group zero must never be signalled')
+            groups.append(group)
+            return killpg(group, sig)
+        with patch.object(sys, 'platform', 'freebsd14'), patch.object(os, 'waitid', None, create=True), \
+                patch.object(subprocess, 'Popen', launch), patch.object(os, 'killpg', signal_group):
+            self.assert_success_retires_socket_owner()
+        self.assertTrue(groups, 'real owned group must be retired')
+        record = json.loads((self.root / 'commands.json').read_text())[-1]
+        data = Path(record['log']).read_bytes()
+        self.assertEqual(0, record['exit'])
+        self.assertEqual(hashlib.sha256(data).hexdigest(), record['sha256'])
+        self.assertNotIn('error', record)
+
     @unittest.skipUnless(os.name == 'posix', 'Darwin unknown scheduling state')
     def test_ps_unknown_state_preserves_complete_numeric_membership(self):
         # Captured native rows: the unknown process belongs to a different group.

specs/tasks/FEATURE-ci-freebsd-pid-zero.md

@@ -0,0 +1,64 @@
+# FEATURE-ci-freebsd-pid-zero: accept the FreeBSD kernel process snapshot
+
+Status: Complete (local implementation, validation and finalization).
+Base: `v3` at `48e4d0208dd0d319e388571481263fb009878d28`.
+
+FreeBSD package job `120396472458` in run `39948363870`, source
+`a68ba478e967988331c167af102189c905b6fe95`, fails during successful command
+cleanup with `invalid command process snapshot PID`, before the library
+matrix runs. That revision and the task base share the exact command module
+blob `e75901dededdf996ef70a4bfa723024825a38122`. The job did not log the
+rejected row, so attribution to kernel PID0 is corroborated rather than
+verified from a raw native row. The same a68 FreeBSD archive job
+`120398555704` / run `39948390044` has the same cleanup rejection after
+Node build completion; its raw log is retained alongside the package log.
+Rejecting legitimate PID0 is independently
+reproduced through the production parser.
+
+The [FreeBSD Architecture Handbook](https://docs.freebsd.org/en/books/arch-handbook/boot/)
+identifies the scheduler/swapper as PID0. The
+[FreeBSD kernel initialization source](https://github.com/freebsd/freebsd-src/blob/releng/14.3/sys/kern/init_main.c)
+places proc0 in pgrp0. The parser now retains numeric PID0 with parent0/group0
+as observation data. Duplicates, malformed or negative fields, invalid states,
+and nonzero parent/group for PID0 still fail closed. Signal targets continue
+to come exclusively from the owned, unreaped, positive-PID session leader.
+
+Action items:
+
+- [x] Use the Groundwork identity helper and isolated worktree from the exact
+  v3 base; preserve unrelated bauth work and closed investigations.
+- [x] Read process safety/TDD guidance and record concrete doubts before code.
+- [x] Reproduce rejection through actual `_process_snapshot` with kernel0,
+  an owned leader, and a live descendant before editing production.
+- [x] Accept only the legitimate zero-parent/group kernel row; retain strict
+  duplicate, malformed, negative, state and empty-snapshot controls.
+- [x] Exercise real command/descendant/socket cleanup and real ps with a
+  kernel row, requiring positive signal targets and preserved output receipts.
+- [x] Preserve leader reservation/reaping, permission errors, exact group
+  targeting, two-observation quiescence and shared cleanup deadlines.
+- [x] Run the affected installed-consumer module, Python syntax and diff checks.
+- [x] Save raw RED/GREEN evidence, source binding and journal in main
+  `.debug/FEATURE-ci-freebsd-pid-zero/`.
+- [x] Caller: Groundwork validation and local finalization into v3.
+- [ ] CI / v3 PR: native FreeBSD package execution and nonlocal checks.
+
+Verification: three existing ps validation/ownership checks passed before
+edits. The new parser and real cleanup tests rejected the valid kernel row
+with the original exception in RED; after the minimal guard correction all
+three new tests pass, including 11 invalid/empty snapshot cases. All 58 tests
+in the affected installed-consumer module pass. Existing permission denial,
+ownership loss, unknown states, late descendants, deadlines and shell controls
+remain covered. Python AST syntax and `git diff --check` pass. CLAUDE.md's C++
+linter does not apply to these Python changes; it documents no Python linter.
+
+These checks use controlled ps data or the local real ps with an added
+kernel row, and real local processes/sockets; they are not native FreeBSD
+receipts. Native checks remain incomplete and CI/v3-PR owned under AGENTS.
+No full native baseline, installation, workflow/runtime changes, validation
+loop, merge or publication was performed. Linux parity and Darwin deadline
+causality remain CLOSED/UNCERTAIN; further Darwin diagnostics still require
+the user's explicit approval.
+
+Project notes: Python standard library tests need no installation. Full
+Autotools/C++20 builds are outside this script-only repair. Groundwork
+returned the exact task path/branch; Git metadata writes need escalation.