codex-mcp-auto-reap

name

codex-mcp-auto-reap

description

Decide whether safe automatic cleanup of terminal Codex native-subagent helper cohorts is needed, ask before enabling it, install or configure only the fixed 60-second policy, and verify the proven cleanup method. Use after Codex restarts or updates, during native-subagent setup, when terminal helper processes linger, or when the user asks to enable, disable, test, inspect, diagnose, or remove auto-cleanup. Do not use for general process cleanup, ordinary memory optimization, Computer Use cleanup, or unrelated MCP failures.

Codex MCP Auto-Reap

Configure and verify one safeguard only. Use the existing Aria collector when the current workspace provides it. Otherwise use the bundled macOS LaunchAgent runtime. The skill itself is not an MCP server.

Resolve the skill directory

Resolve the directory containing this SKILL.md from the active skill installation. Never assume a particular username, home directory, plugin cache version, or checkout path. Use the Python interpreter required by the current workspace. For standalone installation, use a stable Python 3.10 or newer interpreter outside a virtual environment.

Read references/contract.md before configuration.

Inspect without changing state

Run:

<python> <skill-directory>/scripts/configure_auto_reap.py --status
<python> <skill-directory>/scripts/codex_mcp_auto_reap_status.py --json

The helpers automatically use a compatible Aria runtime found at an explicit --aria-root, ARIA_ROOT, or the current workspace ancestry. Otherwise they inspect the standalone installation under the current user's Library/Application Support and Library/LaunchAgents directories.

If the exact enabled configuration and healthy service already exist, report that it is on and continue to verification without asking again. If it is absent, disabled, malformed, incompatible, or missing prerequisites, explain the observed state before offering setup.

Decide whether it is needed

Recommend enabling it when Codex Desktop native subagents are used and terminal helper cohorts can accumulate. Do not recommend it as a generic RAM cleaner or claim that it manages helpers outside the current Codex Desktop app-server.

When the current or preserved request has not already authorized enabling, ask one concrete question in the user's language. Preserve this meaning:

Enable automatic cleanup of terminal Codex subagent helpers on the fixed 60-second scan? It preserves the root session, running or unclear work, and Computer Use.

Offer Enable and Keep off as the two normal choices. Do not mutate configuration while waiting. A clear enable or disable request already answers the question and must not be asked again.

Configure only after consent

Enable only the fixed policy:

<stable-python> <skill-directory>/scripts/configure_auto_reap.py --enable

Disable only when explicitly requested:

<python> <skill-directory>/scripts/configure_auto_reap.py --disable

Uninstall the standalone runtime only when the user explicitly requests deletion:

<python> <skill-directory>/scripts/configure_auto_reap.py --standalone --uninstall

The configuration contains exactly version, enabled, and min_age_seconds. There is no alternate age, keep, CPU, wait, signal, or SIGKILL setting.

Standalone setup installs an immutable copy of the bundled standard-library runtime, writes a direct-argument LaunchAgent with StartInterval=60, and enables it only after launchd accepts the job. It takes a private baseline before changing an existing configuration or plist. It does not run through a shell.

Verify current health

Rerun both read-only status helpers. For standalone installations, require an exact configuration, the expected immutable runtime, a valid direct-argument plist, and a loaded LaunchAgent. For Aria, require the exact configuration, fresh ownership evidence, one protected root cohort, no unresolved cohort for a clean result, and an unblocked collector pass.

ok: true proves current control-plane health. It does not by itself prove that a particular canary cohort was removed.

Reproduce the successful canary

1. Record baseline status and the protected root anchor.
2. Spawn one fresh bounded native subagent that makes a harmless node_repl call and returns an exact canary token.
3. Wait until it reaches a terminal state. Never reuse that terminal agent id.
4. Capture its exact cohort identities before cleanup when practical.
5. Allow the cohort to become at least 60 seconds old. The service scans once per minute, so observed cleanup is normally within roughly 60 to 120 seconds rather than exactly at second 60.
6. Let the normal service scan run, or kickstart its already-installed LaunchAgent when a live verification run is authorized.
7. Rerun status and inspect the latest redacted reap ledger.
8. Claim success only when the root remains protected, the canary cohort is gone, and every previously selected exact identity is absent or has been replaced by a different identity.

Interpret evidence correctly

• A sent SIGTERM is attempt evidence, not final cleanup proof.
• Final proof is later exact-identity absence plus a refreshed ownership result with no matching terminal cohort.
• A reused PID with a different parent, process group, start time, or command hash means the selected identity is absent.
• Missing, invalid, stale, schema-incompatible, ambiguous, or runtime-mismatched evidence blocks termination and a success claim.
• No active Codex Desktop runtime is a safe idle state, not a reason to launch or kill anything.

Preserve the safety boundary

• Preserve the oldest root cohort and every live, unknown, unmatched, ambiguous, or unresolved cohort.
• Require exactly one current Codex Desktop application and child app-server runtime.
• Match a subagent cohort only when the cohort-to-thread match is mutually unique.
• Revalidate every selected PID identity immediately before SIGTERM.
• Never use raw kill, pkill, process-name-only matching, SIGKILL, or broad cleanup commands.
• Exclude the separate SkyComputerUseClient Computer Use transport and helpers not recognized as part of a verified cohort. Do not misclassify the app-bundled general node_repl merely because its current path includes cua_node.
• Fail closed on Codex database or rollout schema drift.
• Keep conclusion-critical verification on the main thread.