Command reference
oko sessions reap
Signals a recorded ended session's remaining process tree, preserving the reason, requested identities and actual outcome.
Invocation#
oko sessions reap PID --reason TEXT [--json]Inputs and options#
- PID must be an attributed root from `oko sessions orphans`. --reason is required and cannot be blank. Every current descendant must have a matching recorded process birth, belong to the same session and have no surviving original owner.
- For example, inspect `oko sessions agents`, then `oko sessions reap PID --reason "process remained after its recorded session ended"` for a listed tree. The operation never infers permission from the command text.
Output and state effect#
- Before signalling, appends and syncs a requested record containing session, reason, process births and tree to ~/.oko/reaped.jsonl. Revalidates identities, sends HUP deepest-first, then retains a finished record with killStatus, killError and remaining. A launch, identity or observation failure after the request is retained in failure and returned as a refusal.
- A process still present immediately afterward remains listed in remaining; sending a signal is not proof of termination. The CLI and native sessions API use the same operation. Desktop preserves a reap refusal even when refreshing the process table succeeds.
- The real sessions-orphans Cargo journey under tests/sessions/orphans starts an isolated real broker, observes a detached descendant, ends its intermediate parent and checks that reap still refuses while the recorded broker owner lives. It then ends that owner and reaps the child. Kernel exit events synchronize the assertions. It also covers missing-reason, unobserved-ownership and already-ended refusals and retains the actual checkout revision, patch, Cargo-built binary identity, commands, exits and reports under .build. The release manifest registers this target as a required test quality gate; registration alone is not a passing result.
Refusals and safe exits#
- A missing process, live starter or original owner, unknown ancestry, reused PID or descendant belonging to another session refuses without signalling. No controlling terminal is required for a recorded detached descendant.
- Missing or invalid PID, missing or empty --reason, unknown flags and unreadable state retain their causes. If the intent cannot be persisted, nothing is signalled. Signal and post-signal observation failures name the operation and the retained outcome.