@@ -614,15 +614,16 @@ type StopSignal = GracefulStopSignal | 'SIGKILL';
614614 *
615615 * - `stopped`: the host released the pid, or proved the pid now names a different process.
616616 * `signal` is the last signal this stop sent before that proof, and is absent when the recorded
617- * process was already gone before anything was signaled.
617+ * process was already gone before anything was signaled. `reassigned` says the proof was a pid
618+ * that now names a different process: the recorded process is gone, but nobody watched it leave.
618619 * - `retained` + `signal-failed`: `signal` was refused by `errno` while the process was there.
619620 * `EPERM` usually means another owner holds it, and later signals are refused by the same check.
620621 * - `retained` + `exit-timeout`: SIGKILL was accepted and the process outlived its budget.
621622 * - `retained` + `identity-unverified`: no recorded claim could be confirmed against a readable fact,
622623 * so nothing proves which process a signal would reach.
623624 */
624625export type ConfirmedProcessStop =
625- | Readonly < { status : 'stopped' ; signal ?: StopSignal } >
626+ | Readonly < { status : 'stopped' ; signal ?: StopSignal ; reassigned ?: true } >
626627 | Readonly < { status : 'retained' ; reason : 'signal-failed' ; signal : StopSignal ; errno : string } >
627628 | Readonly < { status : 'retained' ; reason : 'exit-timeout' ; signal : 'SIGKILL' } >
628629 | Readonly < { status : 'retained' ; reason : 'identity-unverified' } > ;
@@ -721,13 +722,38 @@ export type ProcessStopBudget = Readonly<{
721722 gracefulSignal ?: GracefulStopSignal ;
722723} > ;
723724
725+ /**
726+ * What the host's facts say about the process a caller recorded. One rule answers every identity
727+ * question before a signal:
728+ *
729+ * - `exited`: the host shows the pid as a zombie, so the recorded process already terminated.
730+ * - `reassigned`: a readable start time or command contradicts the record, so the pid now names a
731+ * different process and the recorded one is gone.
732+ * - `ours`: at least one recorded claim is confirmed by a readable fact and none is contradicted.
733+ * - `unverified`: no recorded claim is confirmed. A silent host is never permission to signal.
734+ */
735+ export type ProcessIdentityVerdict = 'ours' | 'exited' | 'reassigned' | 'unverified' ;
736+
737+ export function judgeProcessIdentity (
738+ expected : ProcessStopIdentity ,
739+ facts : HostProcessIdentityFacts ,
740+ ) : ProcessIdentityVerdict {
741+ if ( facts . zombie ) return 'exited' ;
742+ if ( expected . startTime && facts . startTime && facts . startTime !== expected . startTime ) {
743+ return 'reassigned' ;
744+ }
745+ if ( expected . matches && facts . command && ! expected . matches ( facts . command ) ) return 'reassigned' ;
746+ const confirmedStartTime = Boolean ( expected . startTime && facts . startTime ) ;
747+ const confirmedCommand = Boolean ( expected . matches && facts . command ) ;
748+ return confirmedStartTime || confirmedCommand ? 'ours' : 'unverified' ;
749+ }
750+
724751/**
725752 * The one TERM-then-KILL escalation in host-kit. Signals one process gracefully, waits the grace
726753 * period, re-proves identity, then sends SIGKILL, and proves which way the recorded process ended
727- * so a caller only forgets one it watched leave. Identity settles it both ways: unreadable
728- * identity retains rather than signaling a process this caller cannot name, while a released pid,
729- * a zombie, a start time the host contradicts, or a command `identity.matches` rejects proves it
730- * gone. A refusal is not absence, so each stage waits.
754+ * so a caller only forgets one it watched leave. Every signal needs a host-confirmed identity
755+ * ({@link judgeProcessIdentity}): an unreadable identity before either signal retains rather than
756+ * signaling a process this caller cannot name. A refusal is not absence, so each stage waits.
731757 */
732758export async function stopProcessAndConfirmExit (
733759 target : ProcessStopTarget ,
@@ -736,39 +762,41 @@ export async function stopProcessAndConfirmExit(
736762 // Stale or malformed process state must never aim a signal at the caller itself.
737763 if ( target . pid === process . pid ) throw new RangeError ( 'Cannot stop the current process' ) ;
738764 const identity = await proveStopTargetIdentity ( target ) ;
739- if ( identity === 'gone' ) return { status : 'stopped' } ;
765+ if ( identity === 'released' || identity === 'exited' ) return { status : 'stopped' } ;
766+ if ( identity === 'reassigned' ) return { status : 'stopped' , reassigned : true } ;
740767 if ( identity === 'unverified' ) return { status : 'retained' , reason : 'identity-unverified' } ;
741768 const graceful = budget . gracefulSignal ?? 'SIGTERM' ;
742769 const term = await proveSignalStage ( target , graceful , budget . termTimeoutMs ) ;
743- if ( term . proof === 'exited' ) return { status : 'stopped' , signal : graceful } ;
744- // A refused graceful signal is the whole verdict: the host refuses SIGKILL by the same
745- // permission check, so escalating would spend a second budget repeating it.
746- if ( term . proof === 'refused' ) return retainedSignalFailure ( graceful , term . errno ) ;
770+ if ( term . proof !== 'survived' ) return stageVerdict ( term , graceful ) ;
747771 const kill = await proveSignalStage ( target , 'SIGKILL' , budget . killTimeoutMs ) ;
748- if ( kill . proof === 'exited' ) return { status : 'stopped' , signal : 'SIGKILL' } ;
749- if ( kill . proof === 'refused' ) return retainedSignalFailure ( 'SIGKILL' , kill . errno ) ;
772+ if ( kill . proof !== 'survived' && kill . proof !== 'unverified' )
773+ return stageVerdict ( kill , 'SIGKILL' ) ;
750774 return { status : 'retained' , reason : 'exit-timeout' , signal : 'SIGKILL' } ;
751775}
752776
777+ /** The verdict a signal stage settles on its own, before any further signal. */
778+ function stageVerdict (
779+ stage : Exclude < SignalStageProof , { proof : 'survived' } > ,
780+ signal : StopSignal ,
781+ ) : ConfirmedProcessStop {
782+ if ( stage . proof === 'exited' ) return { status : 'stopped' , signal } ;
783+ if ( stage . proof === 'reassigned' ) return { status : 'stopped' , signal, reassigned : true } ;
784+ // A refused graceful signal is the whole verdict: the host refuses SIGKILL by the same
785+ // permission check, so escalating would spend a second budget repeating it.
786+ if ( stage . proof === 'refused' ) return retainedSignalFailure ( signal , stage . errno ) ;
787+ // The pid outlived the grace period and the host will not say what it is now.
788+ return { status : 'retained' , reason : 'identity-unverified' } ;
789+ }
790+
753791/**
754792 * Whether the live pid still names the process the caller recorded, read once before anything is
755- * signaled. `ours` needs a claim the host confirmed: two recorded facts that no readable fact
756- * contradicts only prove the host is silent, and silence about a pid this caller may not own is
757- * exactly what must not become permission to signal it.
793+ * signaled. `released` is a pid `kill(pid, 0)` no longer finds; the rest is {@link judgeProcessIdentity}.
758794 */
759795async function proveStopTargetIdentity (
760796 target : ProcessStopTarget ,
761- ) : Promise < 'ours' | 'gone' | 'unverified' > {
762- if ( ! isStopPidLive ( target . pid ) ) return 'gone' ;
763- const facts = await readProcessIdentityFacts ( target . pid ) ;
764- if ( facts . zombie ) return 'gone' ;
765- if ( target . identity . startTime && facts . startTime && facts . startTime !== target . identity . startTime )
766- return 'gone' ;
767- if ( target . identity . matches && facts . command && ! target . identity . matches ( facts . command ) )
768- return 'gone' ;
769- const confirmedStartTime = Boolean ( target . identity . startTime && facts . startTime ) ;
770- const confirmedCommand = Boolean ( target . identity . matches && facts . command ) ;
771- return confirmedStartTime || confirmedCommand ? 'ours' : 'unverified' ;
797+ ) : Promise < ProcessIdentityVerdict | 'released' > {
798+ if ( ! isStopPidLive ( target . pid ) ) return 'released' ;
799+ return judgeProcessIdentity ( target . identity , await readProcessIdentityFacts ( target . pid ) ) ;
772800}
773801
774802function retainedSignalFailure ( signal : StopSignal , errno : string ) : ConfirmedProcessStop {
@@ -777,10 +805,15 @@ function retainedSignalFailure(signal: StopSignal, errno: string): ConfirmedProc
777805
778806/** What one signal stage proved, within the budget that stage was given. */
779807type SignalStageProof =
780- | Readonly < { proof : 'exited' } >
781- | Readonly < { proof : 'refused' ; errno : string } >
782- | Readonly < { proof : 'survived' } > ;
808+ | Readonly < { proof : 'exited' | 'reassigned' | 'unverified' | 'survived' } >
809+ | Readonly < { proof : 'refused' ; errno : string } > ;
783810
811+ /**
812+ * Sends one signal and waits its budget. A pid that outlives the budget is judged again, which is
813+ * also the identity proof the next signal needs: `kill(pid, 0)` cannot tell, because `EPERM` also
814+ * comes back for a zombie awaiting its parent, and on Windows for a process that exited while its
815+ * object still had handles.
816+ */
784817async function proveSignalStage (
785818 target : ProcessStopTarget ,
786819 signal : StopSignal ,
@@ -791,8 +824,11 @@ async function proveSignalStage(
791824 // owner may release it inside this budget, and a released pid is what the caller may forget.
792825 if ( errno === 'ESRCH' ) return { proof : 'exited' } ;
793826 if ( await waitForStopPidRelease ( target . pid , timeoutMs ) ) return { proof : 'exited' } ;
794- if ( await proveRecordedProcessGone ( target ) ) return { proof : 'exited' } ;
795- return errno === undefined ? { proof : 'survived' } : { proof : 'refused' , errno } ;
827+ const verdict = await proveStopTargetIdentity ( target ) ;
828+ if ( verdict === 'released' || verdict === 'exited' ) return { proof : 'exited' } ;
829+ if ( verdict === 'reassigned' ) return { proof : 'reassigned' } ;
830+ if ( errno !== undefined ) return { proof : 'refused' , errno } ;
831+ return { proof : verdict === 'unverified' ? 'unverified' : 'survived' } ;
796832}
797833
798834const STOP_LIVENESS_POLL_MS = 50 ;
@@ -824,22 +860,6 @@ async function waitForStopPidRelease(pid: number, timeoutMs: number): Promise<bo
824860 }
825861}
826862
827- /**
828- * Whether the pid outliving its budget still proves the recorded process is gone, which the answer to
829- * `kill(pid, 0)` cannot: `EPERM` also comes back for a zombie awaiting its parent, and on Windows for
830- * a process that exited while its object still had handles. A start time the host contradicts proves
831- * the pid changed hands, and a command `identity.matches` rejects proves it no longer runs what this
832- * stop was meant for, so the next stage never signals it; the process table holding no row does not,
833- * because a hidden or unreadable process is missing from it too.
834- */
835- async function proveRecordedProcessGone ( target : ProcessStopTarget ) : Promise < boolean > {
836- const facts = await readProcessIdentityFacts ( target . pid ) ;
837- if ( facts . zombie ) return true ;
838- const { startTime, matches } = target . identity ;
839- if ( startTime && facts . startTime && facts . startTime !== startTime ) return true ;
840- return Boolean ( matches && facts . command && ! matches ( facts . command ) ) ;
841- }
842-
843863/** The errno that refused the signal, or `undefined` when the host accepted it. */
844864function signalProcessForStop ( pid : number , signal : StopSignal ) : string | undefined {
845865 // A non-positive pid is no process at all: `kill(0, …)` would address our own process group.
0 commit comments